Inject Client Scripts

TestCafe allows you to inject custom client scripts into pages visited during the tests. You can add scripts that mock browser API or provide helper functions.

Use test run options to add client scripts to all tests, or test API to add them to specific fixtures or tests.

Add Client Scripts to All Tests

Use either of the following options to inject scripts into pages visited during all the tests:

  • the --cs (--client-scripts) command line option

    testcafe chrome test.js --client-scripts mockDate.js,assets/react-helpers.js

  • the runner.clientScripts API method

    runner.clientScripts('mockDate.js', 'scripts/react-helpers.js');

  • the clientScripts configuration file property

    {
    "clientScripts": ["mockDate.js", "scripts/react-helpers.js"]
}

Add Client Scripts to Specific Tests

Use the fixture.clientScripts and test.clientScripts methods to inject scripts into pages visited during a test or fixture.

fixture `My fixture`
    .page `http://example.com`
    .clientScripts('assets/jquery.js');

test
    ('My test', async t => { /* ... */ })
    .clientScripts({ module: 'async' });

Provide Scripts to Inject

You can pass the following arguments to specify the scripts to inject:

You can also inject scripts into specific pages and iframes.

Note that the API methods and configuration options support multiple arguments.

Inject a JavaScript File

Specify the JavaScript file path to inject the content of this file into the tested pages. You can pass a string or object with the path property.

testcafe chrome my-tests --cs assets/jquery.js

runner.clientScripts('assets/jquery.js');

{
    "clientScripts": "assets/jquery.js"
}

See the details for:

Inject a Module

Specify the Node.js module's name to inject its content into the tested pages. Use an object with the module property.

fixture `My fixture`
    .page `https://example.com`
    .clientScripts({ module: 'lodash' });

{
    "clientScripts": {
        "module": "lodash"
    }
}

TestCafe uses Node.js mechanisms to search for the module's entry point and injects its content into the tested page.

Note that the browser must be able to execute the injected module. For example, modules that implement the UMD API can run in most modern browsers.

See details for:

Inject Script Code

You can pass an object with the content property to provide the injected script as a string.

const mockDate = `
    Date.prototype.getTime = function () {
        return 42;
    };
`;

test
    ('My test', async t => { /* ... */ })
    .clientScripts({ content: mockDate });

{
    "clientScripts": {
        "content": "Date.prototype.getTime = () => 42;"
    }
}

See the details for:

Provide Scripts for Specific Pages

You can also specify pages into which a script should be injected. This will allow you to mock browser API on specified pages and use the default behavior everywhere else.

To specify target pages for a script, add the page property to the object you pass to clientScripts.

runner.clientScripts({
    page: /\/user\/profile\//,
    path: 'dist/jquery.js'
});

{
    "clientScripts": {
        "page": "https://myapp.com/page/",
        "content": "Geolocation.prototype.getCurrentPosition = () => new Positon(0, 0);"
    }
}

See the details for:

Inject Scripts Into Iframes

To inject a script into an iframe, specify the iframe URL in the page property.

runner.clientScripts({
    path: 'scripts/helpers.js',
    page: 'https://example.com/iframe/'
}));

Specify Multiple Scripts

You can pass multiple arguments or an array to the clientScripts methods:

fixture `My fixture`
    .page `https://example.com`
    .clientScripts('scripts/react-helpers.js', { content: 'Date.prototype.getTime = () => 42;' });

runner.clientScripts(['scripts/react-helpers.js', 'dist/jquery.js']);

The clientScripts configuration file property can also take arrays:

{
    "clientScripts": ["vue-helpers.js", {
        "page": "https://mycorp.com/login/",
        "module": "lodash"
    }]
}

The --cs (--client-scripts) command line option supports multiple arguments as well:

testcafe chrome test.js --client-scripts mockDate.js,assets/react-helpers.js

Note that the page, content and module properties cannot take arrays. To inject multiple scripts into the same page, pass one argument for each script.

const scripts = ['test1.js', 'test2.js', 'test3.js'];

runner.clientScripts(scripts.map(script => {
    path: script,
    page: 'http://example.com'
}));

Access DOM in the Injected Scripts

TestCafe injects custom scripts into the head tag. These scripts are executed before the DOM is loaded.

To access the DOM in these scripts, wait until the DOMContentLoaded event fires:

const scriptContent = `
window.addEventListener('DOMContentLoaded', function () {
    document.body.style.backgroundColor = 'green';
});
`;

fixture `My fixture`
    .clientScripts({ content: scriptContent });