Configuration File & Before and After Run Hooks

Learn about the configuration file and its hooks

The configuration file is a common JS containing all the required parameters to run your test and/or test suite. It includes run hooks which can be used to setup the application backend and define parameters before/after a single test or all tests.

The configuration file needs to export all properties in a JSON named config.

Here is an example of a configuration file:

exports.config = {

    project: "<your project ID>",
    token: "<Your token>",
    
    // Specify which label you would like to run. All tests with the 
    // specified label will be executed
    label: "sanity",
    
    // Your Selenium grid
    grid: "<Your grid name>",
    
    // Override the base URL defined in the test in order to run it again on a different envinronment.
    baseUrl: 'http://staging.example.com',

    // =====
    // Hooks
    // =====
    // Testim provides several hooks you can use to interfere the test 
    // process in order to enhance it and build services around it.
   
    // Hook that gets executed before the suite starts
    beforeSuite: function (suite) {
        console.log("beforeSuite", suite);
    },
    
    // Function to be executed before a test starts.
    beforeTest: function (test) {
        console.log("beforeTest", test);
    },
    
    // Function to be executed after a test ends.
    afterTest: function (test) {
        console.log("afterTest", test);
    },
    
    // Hook that gets executed after the suite has ended
    afterSuite: function (suite) {
        console.log("afterSuite", suite);
    }
};

📘

For the grid name, read Grid Management how to set up your grid.

Syntax

The configuration file supports all the properties described in the CLI actions
The name structure of the property is slightly different, replace the hyphen(-) with a capital letter. For example: base-url => baseUrl.

When you need to send more than one value to a parameter, use an array.
For example: label: ["a" , "b"]

Using the beforeTest hook to get a list of labels in runtime

As part of the beforeTest hook in the config file, it is possible to define a parameter and populate it with a list of labels that were defined for the test.
In the following example, we defined a parameter called labels. This parameter will contain the list of labels that were included in the specific test. The parameter can then be used anywhere where parameters are used. For example, in a Custom Step you can include code that defines that if the test was tagged with label Games, the step should be skipped.

To learn more about using parameters, see Parameters

beforeTest: function(test) {
    return {
        labels: test.allLabels
    }
}

Using the beforeTest hook to update the base-url variable

As part of the beforeTest hook in the config file, it is possible to get the base-url of a test and to update the base-url variable with an updated value.
In the following example, we get the current test base URL and then update the test base URL with a different value.
To learn more about using parameters, see Parameters

exports.config = {
    // Function to be executed before a test starts.
    async beforeTest(test) {
        const baseUrl = test.config.baseUrl; // Get the current test base URL.
        const randomAddress = await getRandomAddress();
        test.config.baseUrl = `${baseUrl}${randomAddress}`; // Update the test base URL using a manipulation on the existing base URL.
    }
};

Global exports parameters

In "afterSuite" function you can use exports global parameters exported in your run.
Syntax: suite.exportsGlobal.<param_name>
Read more about exports global parameters here.

Running a Test Using the Config File

  1. Create your configuration file (e.g. testimConfig.js)
  2. Pass it to the Command Line (CLI) runner as a parameter:
  3. Make sure to indicate the path to the file if needed.
testim -c "testimConfig.js"
  1. If you want to override one of the values in the configuration file, simply pass it explicitly to the CLI, like this:
testim -c "testimConfig.js" --label "nightly"