Configuration File

When you launch TestCafe from the command line, you can specify launch options, like so: testcafe all tests/sample-fixture.js -q.

As the list of options grows in size, it becomes harder to maintain. This is why launch settings should be stored in a dedicated configuration file.

Configuration conflicts

Command line options and TestCafe Runner options have precedence over configuration file settings. When TestCafe overrides a configuration file setting, it outputs a description of the conflict to the console.

Set-up

Location

On startup, TestCafe looks for a configuration file (.testcaferc.js or .testcaferc.json) in the current working directory. If you store the configuration file elsewhere, you can specify the path to a custom configuration file with the --config-file command line option.

Name

The default base name for the configuration file is .testcaferc. Set the --config-file command line option to use a configuration file with a custom name.

TestCafe supports two configuration file formats: .js and .json. Take a look at the Formats section for a comparison of these configuration file formats.

Configuration file priority

TestCafe can only use one configuration file at a time.

  • If a user does not set the --config-file option, TestCafe searches the current working directory for a file named .testcaferc.js.
  • If .testcaferc.js does not exist, TestCafe looks for a file named .testcaferc.json.
  • If neither file exists, TestCafe does not load any configuration files.

Formats

JSON

JSON configuration files store settings in key-value pairs. JSON configuration files adhere to the JSON5 standard — they support JavaScript identifiers as object keys, single-quoted strings, comments, and other modern features.

.testcaferc.json:

{
    skipJsErrors: true,
    hostname: "localhost",
    // other settings
}

You can find a sample JSON configuration file in the GitHub repository.

JavaScript

JavaScript configuration files store settings in key-value pairs within a module.exports statement. TestCafe cannot access the settings that the user did not export.

Configuration properties in JavaScript files can reference JavaScript methods, functions and variables, which makes it easy to create dynamic configuration files.

.testcaferc.js:

let os = require("os");

module.exports = {
    skipJsErrors: true,
    hostname: os.hostname(),
    // other settings
}

Settings

Configuration files can include the following settings:

browsers

Specifies one or several browsers in which a test should run.

You can use browser aliases to specify locally installed browsers.

{
    "browsers": "chrome"
}
{
    "browsers": ["ie", "firefox"]
}

Use the all alias to run tests in all the installed browsers.

Use the path: prefix to specify a path to the browser’s executable file. Enclose the path in backticks if it contains spaces.

{
    "browsers": "path:`C:\\Program Files\\Internet Explorer\\iexplore.exe`"
}

Alternatively, you can pass an object whose path property specifies the path to the browser’s executable file. In this case, you can also use an optional cmd property to specify command line parameters passed to the browser.

{
    "browsers": {
        "path": "/home/user/portable/firefox.app",
        "cmd": "--no-remote"
    }
}

To run tests in cloud browsers or other browsers accessed through a browser provider plugin, specify the browser’s alias that consists of the {browser-provider-name} prefix and the name of the browser (the latter can be omitted); for example, saucelabs:Chrome@52.0:Windows 8.1.

{
    "browsers": "saucelabs:Chrome@52.0:Windows 8.1"
}

To run tests in a browser on a remote device, specify remote as a browser alias.

If you want to connect multiple browsers, specify remote: and the number of browsers. For example, if you need to use four remote browsers, specify remote:4.

{
    "browsers": "remote:4"
}

You can add postfixes to browser aliases to run tests in headless mode, use Chrome device emulation or user profiles.

{
    "browsers": ["firefox:headless", "chrome:emulation:device=iphone X"]
}

Note

You cannot add postfixes when you use the path: prefix or pass a { path, cmd } object.

CLI: Browser List
API: runner.browsers, BrowserConnection

src

Specifies files or directories from which to run tests.

TestCafe can run tests from the following file types:

  • JavaScript, TypeScript and CoffeeScript files that use TestCafe API.
  • TestCafe Studio tests (.testcafe files).
  • Legacy TestCafe v2015.1 tests.
{
    "src": "/home/user/tests/fixture.js"
}
{
    "src": ["/home/user/auth-tests/fixture.testcafe", "/home/user/mobile-tests/"]
}

You can use glob patterns to specify a set of files.

{
    "src": ["/home/user/tests/**/*.js", "!/home/user/tests/foo.js"]
}

CLI: File Path/Glob Pattern
API: runner.src

reporter

Specifies the name of a built-in or custom reporter that generates test reports.

{
    "reporter": "list"
}

This configuration outputs the test report to stdout. To save a report to a file, pass an object whose name property specifies the reporter name and output property specifies the path to the file.

{
    "reporter": {
        "name": "xunit",
        "output": "reports/report.xml"
    }
}

You can use multiple reporters, but note that only one reporter can write to stdout. All other reporters must output to files.

{
    "reporter": [
        {
            "name": "spec"
        },
        {
            "name": "json",
            "output": "reports/report.json"
        }
    ]
}

CLI: -r, --reporter
API: runner.reporter

screenshots

Allows you to specify the screenshot options.

screenshots.path

Specifies the base directory where to save screenshots.

{
    "screenshots": {
        "path": "/home/user/tests/screenshots/"
    }
}

See Screenshots for details.

CLI: --screenshots path
API: runner.screenshots

screenshots.takeOnFails

Specifies whether to take a screenshot when a test fails.

{
    "screenshots": {
        "takeOnFails": true
    }
}

TestCafe saves screenshots to the directory specified in the screenshots.path property.

CLI: --screenshots takeOnFails
API: runner.screenshots

screenshots.pathPattern

Specifies a custom pattern to compose screenshot files’ relative path and name.

{
    "screenshots": {
        "pathPattern": "${DATE}_${TIME}/test-${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png"
    }
}

See Path Pattern Placeholders for information about available placeholders.

CLI: --screenshots pathPattern
API: runner.screenshots

screenshots.fullPage

Specifies whether to capture the full page, including invisible elements.

{
    "screenshots": {
        "fullPage": true
    }
}

CLI: --screenshots fullPage
API: runner.screenshots

screenshots.thumbnails

Specifies whether to make thumbnails for captured screenshots.

{
    "screenshots": {
        "thumbnails": false
    }
}

TestCafe saves thumbnails to the directory specified in the screenshots.path property.

CLI: --screenshots thumbnails
API: runner.screenshots

disableScreenshots

Prevents TestCafe from taking screenshots.

{
    "disableScreenshots": true
}

When this property is specified, TestCafe does not take screenshots when a test fails and ignores the screenshot action.

CLI: --disable-screenshots
API: runner.run({ disableScreenshots })

screenshotPath

Obsolete. Enables screenshots and specifies the base directory where they are saved.

{
    "screenshotPath": "/home/user/tests/screenshots/"
}

In v1.5.0 and later, screenshots are enabled by default and saved to ./screenshots.

To save them to a different location, specify the screenshots.path property:

{
    "screenshots": {
        "path": "/home/user/tests/screenshots/"
    }
}

Use the disableScreenshots property to prevent TestCafe from taking screenshots:

{
    "disableScreenshots": true
}

takeScreenshotsOnFails

Obsolete. Specifies that TestCafe should take a screenshot whenever a test fails.

{
    "takeScreenshotsOnFails": true
}

In v1.5.0 and later, use the screenshots.takeOnFails property:

{
    "screenshots": {
        "takeOnFails": true
    }
}

screenshotPathPattern

Obsolete. Specifies a custom pattern to compose screenshot files’ relative path and name.

{
    "screenshotPathPattern": "${DATE}_${TIME}/test-${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png"
}

In v1.5.0 and later, use the screenshots.pathPattern property:

{
    "screenshots": {
        "pathPattern": "${DATE}_${TIME}/test-${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png"
    }
}

videoPath

Enables TestCafe to record videos of test runs and specifies the base directory to save these videos.

{
    "videoPath": "reports/screen-captures"
}

See Record Videos for details.

CLI: --video
API: runner.video

videoOptions

Specifies options that define how TestCafe records videos of test runs.

{
    "videoOptions": {
        "singleFile": true,
        "failedOnly": true,
        "pathPattern": "${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.mp4"
    }
}

See Basic Video Options for available options.

Note

Use the videoPath option to enable video recording.

CLI: --video-options
API: runner.video

videoEncodingOptions

Specifies video encoding options.

{
    "videoEncodingOptions": {
        "r": 20,
        "aspect": "4:3"
    }
}

You can pass all the options supported by the FFmpeg library. Refer to the FFmpeg documentation for information about all available options.

Note

Use the videoPath option to enable video recording.

CLI: --video-encoding-options
API: runner.video

quarantineMode

Enable quarantine mode to eliminate false negatives and detect unstable tests. TestCafe quarantines tests that fail and repeats them until they yield conclusive results.

{
    "quarantineMode": true
}

CLI: -q, --quarantine-mode
API: runner.run({ quarantineMode })

quarantineMode.successThreshold

The number of successful attempts necessary to confirm a test’s success. The option value should be greater than 0. The default value is 3.

{
    "quarantineMode": {
        "successThreshold": 2
    }
}

CLI: -q successThreshold=N, --quarantine-mode successThreshold=N
API: runner.run({ quarantineMode: { successThreshold: N } })

quarantineMode.attemptLimit

The maximum number of test execution attempts. The option value should exceed the value of the successThreshold. The default value is 5.

{
    "quarantineMode": {
        "attemptLimit": 3
    }
}

CLI: -q attemptLimit=N, --quarantine-mode attemptLimit=N
API: runner.run({ quarantineMode: { attemptLimit: N } })

debugMode

Runs tests in debug mode.

{
    "debugMode": true
}

See the --debug-mode command line parameter for details.

CLI: -d, --debug-mode
API: runner.run({ debugMode })

debugOnFail

Specifies whether to enter debug mode when a test fails.

{
    "debugOnFail": true
}

If this option is enabled, TestCafe pauses the test when it fails. This allows you to view the tested page and determine the cause of the fail.

Click the Finish button in the footer to end test execution.

CLI: --debug-on-fail
API: runner.run({ debugOnFail })

skipJsErrors

Ignores JavaScript errors on a webpage.

{
    "skipJsErrors": true
}

When a JavaScript error occurs on a tested web page, TestCafe stops test execution and posts an error message and a stack trace to a report. To ignore JavaScript errors, set the skipJsErrors property to true.

CLI: -e, --skip-js-errors
API: runner.run({ skipJsErrors })

skipUncaughtErrors

Ignores uncaught errors and unhandled promise rejections in test code.

{
    "skipUncaughtErrors": true
}

When an uncaught error or unhandled promise rejection occurs on the server during test execution, TestCafe stops the test and posts an error message to a report. To ignore these errors, use the skipUncaughtErrors property.

CLI: -u, --skip-uncaught-errors
API: runner.run({ skipUncaughtErrors })

filter

Allows you to specify which tests or fixtures to run. Use the following properties individually or in combination.

filter.test

Runs a test with the specified name.

{
    "filter": {
        "test": "Click a label"
    }
}

CLI: -t, --test
API: runner.filter

filter.testGrep

Runs tests whose names match the specified grep pattern.

{
    "filter": {
        "testGrep": "Click.*"
    }
}

CLI: -T, --test-grep
API: runner.filter

filter.fixture

Runs a test with the specified fixture name.

{
    "filter": {
        "fixture": "Sample fixture"
    }
}

CLI: -f, --fixture
API: runner.filter

filter.fixtureGrep

Runs tests whose fixture names match the specified grep pattern.

{
    "filter": {
        "fixtureGrep": "Page.*"
    }
}

CLI: -F, --fixture-grep
API: runner.filter

filter.testMeta

Runs tests whose metadata matches the specified key-value pair.

{
    "filter": {
        "testMeta": {
            "device": "mobile",
            "env": "production"
        }
    }
}

This configuration runs tests whose metadata’s device property is set to mobile and the env property is set to production.

CLI: --test-meta
API: runner.filter

filter.fixtureMeta

Runs tests whose fixture’s metadata matches the specified key-value pair.

{
    "filter": {
        "fixtureMeta": {
            "device": "mobile",
            "env": "production"
        }
    }
}

This configuration runs tests whose fixture’s metadata has the device property set to mobile and the env property set to the production.

CLI: --fixture-meta
API: runner.filter

appCommand

Executes a shell command and runs tests.

{
    "appCommand": "node server.js"
}

Use the appCommand property to launch the application you need to test. TestCafe terminates this application after testing is completed.

The appInitDelay property specifies the amount of time allowed for this command to initialize the tested application.

Note

TestCafe adds node_modules/.bin to PATH, so that you can use the binaries from the locally installed dependencies without prefixes.

CLI: -a, --app
API: runner.startApp

appInitDelay

Specifies the time (in milliseconds) during which an application is initialized if you launch the application with the --app option.

TestCafe waits for the specified time before it starts tests.

{
    "appCommand": "node server.js",
    "appInitDelay": 3000
}

Default value: 1000

CLI: --app-init-delay
API: runner.startApp

concurrency

Specifies the number of browser instances that should run tests concurrently.

{
    "concurrency": 3
}

TestCafe opens several instances of the same browser and creates a pool of browser instances. Tests are run concurrently against this pool; that is, each test is run in the first free instance.

See Concurrent Test Execution for more information about concurrent test execution.

CLI: -c, --concurrency
API: runner.concurrency

selectorTimeout

Specifies the time (in milliseconds) within which selectors attempt to return a node. See Selector Timeout for details.

{
    "selectorTimeout": 3000
}

Default value: 10000

CLI: --selector-timeout
API: runner.run({ selectorTimeout })

assertionTimeout

Specifies the time (in milliseconds) within which TestCafe attempts to successfully execute an assertion if you pass a selector property or a client function as an actual value.

See Smart Assertion Query Mechanism.

{
    "assertionTimeout": 1000
}

Default value: 3000

CLI: --assertion-timeout
API: runner.run({ assertionTimeout })

pageLoadTimeout

Specifies the time (in milliseconds) passed after the DOMContentLoaded event within which TestCafe waits for the window.load event to fire.

After the timeout passes or the window.load event is raised (whichever happens first), TestCafe starts the test.

{
    "pageLoadTimeout": 1000
}

Default value: 3000

See the command line --page-load-timeout parameter for details.

CLI: --page-load-timeout
API: runner.run({ pageLoadTimeout })

ajaxRequestTimeout

Specifies wait time (in milliseconds) for fetch/XHR requests. If TestCafe receives no response within the specified period, it throws an error.

{
    "ajaxRequestTimeout": 40000
}

Default value: 120000

CLI: --ajax-request-timeout

pageRequestTimeout

Specifies time (in milliseconds) to wait for HTML pages. If TestCafe does not receive a page within the specified period, it throws an error.

{
    "pageRequestTimeout": 8000
}

Default value: 25000

CLI: --page-request-timeout

browserInitTimeout

Time (in milliseconds) for browsers to connect to TestCafe and report that they are ready to test. If one or more browsers fail to connect within the specified period, TestCafe throws an error.

{
    "browserInitTimeout": 180000
}

In this example, the timeout for local and remote browsers is three minutes. In this run, all browsers have to connect within this time before TestCafe throws an error.

Default values:

CLI: --browser-init-timeout
API: runner.run({ browserInitTimeout })

speed

Specifies the test execution speed.

If this option is not specified, TestCafe runs tests at the maximum speed. You can use this option to slow a test down. The number range is between 1 (the fastest) and 0.01 (the slowest).

{
    "speed": 0.1
}

Default value: 1

If you specify the speed for an individual action, the action’s speed setting overrides the test speed.

CLI: --speed
API: runner.run({ speed })

clientScripts

Injects scripts into pages visited during tests. Use this property to introduce client-side mock functions or helper scripts.

{
    "clientScripts": [
        {
            "module": "lodash"
        },
        {
            "path": "scripts/react-helpers.js",
            "page": "https://myapp.com/page/"
        }
    ]
}

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.

{
    "clientScripts": "<filePath>" | { "path": "<filePath>" }
}
{
    "clientScripts": [ "<filePath>" | { "path": "<filePath>" } ]
}
Argument Type Description
filePath String The path to the JavaScript file whose content should be injected.

Note

You cannot combine the path, module and content properties in a single object. To inject multiple items, pass several arguments or an array.

Relative paths are resolved against the current working directory.

Example

{
    "clientScripts": "assets/jquery.js",
    // or
    "clientScripts": { "path": "assets/jquery.js" }
}

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.

{
    "clientScripts": { "module": "<moduleName>" }
}
{
    "clientScripts": [ { "module": "<moduleName>" } ]
}
Argument Type Description
moduleName String The module name.

Note

You cannot combine the module, path and content properties in a single object. To inject multiple items, pass several arguments or an array.

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

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

Note

If the injected module has dependencies, ensure that the dependencies can be loaded as global variables and these variables are initialized in the page’s code.

Example

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

Inject Script Code

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

{
    "clientScripts": { "content": "<code>" }
}
{
    "clientScripts": [ { "content": "<code>" } ]
}
Argument Type Description
code String JavaScript that should be injected.

Note

You cannot combine the content, path and module properties in a single object. To inject multiple items, pass several arguments or an array.

Example

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

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.

{
    "clientScripts": {
        "page": "<url>",
        "path": "<filePath>" | "module": "<moduleName>" | "content": "<code>"
    }
}
{
    "clientScripts": [
        {
            "page": "<url>",
            "path": "<filePath>" | "module": "<moduleName>" | "content": "<code>"
        }
    ]
}
Property Type Description
url String Specify a page URL to add scripts to a page.

Note

If the target page redirects to a different URL, ensure that the page property matches the destination URL. Otherwise, scripts are not injected.

Example

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

Note

Note that regular expressions are not supported in the configuration file. Use the following APIs to define target pages with a regular expression:

The fixture.clientScripts and test.clientScripts methods allow you to inject scripts into pages visited during an individual fixture or test.

For more information, see Inject Scripts into Tested Pages.

CLI: --cs, --client-scripts
API: runner.clientScripts

port1, port2

Specifies custom port numbers TestCafe uses to perform testing. The number range is [0-65535].

{
    "port1": 12345,
    "port2": 54321
}

TestCafe automatically selects ports if ports are not specified.

CLI: --ports
API: createTestCafe

hostname

Specifies your computer’s hostname. TestCafe uses this hostname when you run tests in remote browsers.

{
    "hostname": "host.mycorp.com"
}

If the hostname is not specified, TestCafe uses the operating system’s hostname or the current machine’s network IP address.

CLI: --hostname
API: createTestCafe

proxy

Specifies the proxy server used in your local network to access the Internet.

{
    "proxy": "proxy.corp.mycompany.com"
}
{
    "proxy": "172.0.10.10:8080"
}

You can also specify authentication credentials with the proxy host.

{
    "proxy": "username:password@proxy.mycorp.com"
}

CLI: --proxy
API: runner.useProxy

proxyBypass

Requires that TestCafe bypasses the proxy server to access specified resources.

{
    "proxyBypass": "*.mycompany.com"
}
{
    "proxyBypass": ["localhost:8080", "internal-resource.corp.mycompany.com"]
}

See the --proxy-bypass command line parameter for details.

CLI: --proxy-bypass
API: runner.useProxy

ssl

Provides options that allow you to establish an HTTPS connection between the client browser and the TestCafe server.

{
    "ssl": {
        "pfx": "path/to/file.pfx",
        "rejectUnauthorized": true
    }
}

See the --ssl command line parameter for details.

CLI: --ssl
API: createTestCafe

developmentMode

Enables mechanisms to log and diagnose errors. Enable this option if you plan to contact TestCafe Support to report an issue.

{
    "developmentMode": true
}

CLI: --dev
API: createTestCafe

qrCode

If you launch TestCafe from the console, this option outputs a QR code that contains URLs used to connect the remote browsers.

{
    "qrCode": true
}

CLI: --qr-code

stopOnFirstFail

Stops a test run if a test fails.

{
    "stopOnFirstFail": true
}

CLI: --sf, --stop-on-first-fail
API: runner.run({ stopOnFirstFail })

tsConfigPath

Deprecated as of TestCafe v.1.10.0 in favor of the compilerOptions setting.

CLI: --ts-config-path
API: runner.tsConfigPath

compilerOptions

Specifies test compilation settings. The current version of TestCafe can only configure the TypeScript compiler.

{
    "compilerOptions": {
         "typescript": {
              "customCompilerModulePath": "path to custom Typescript compiler module",
              "options": { "experimentalDecorators": "true",  "newLine": "crlf"}
    }
}

Populate the typescript.options object with TypeScript compiler options.

Set the typescript.configPath parameter to load TypeScript compilation settings from a dedicated tsconfig.json file.

{
    "compilerOptions": {
         "typescript": { "configPath": "path-to-custom-ts-config.json"}
    }
}

Set the typescript.compilerModulePath parameter to load an external TypeScript compiler.

{
   "compilerOptions": {
       "typescript":   { "customCompilerModulePath": "path to custom Typescript compiler module" }
    }
}

Note

TestCafe resolves user-specified relative paths against the TestCafe installation folder.

CLI: --compiler-options API: runner.compilerOptions

cache

If this option is enabled, the TestCafe proxy caches assets (such as stylesheets and scripts) of the processed web pages. The next time the proxy accesses the page, it pulls assets from its cache instead of requesting them from the server.

testcafe chrome my-tests --cache

TestCafe emulates the browser’s native caching behavior. For example, in Chrome, TestCafe only caches resources that Chrome itself would cache if run without TestCafe.

TestCafe caches scripts, stylesheets, fonts, and other assets up to 5 MB in size. TestCafe does not cache HTML because that could break user roles.

If the tested application loads many heavy assets, enable server-side caching to decrease test run time.

Important! Support for server-side caching is experimental. Disable the --cache flag if you run into compatibility issues with your tests.

CLI: --cache
API: createTestCafe

disablePageCaching

Prevents the browser from caching page content.

{
    "disablePageCaching": true
}

Users may inadvertently access cached pages that contain outdated automation scripts, for example, when they activate a Role. This can lead to TestCafe errors. If you encounter this issue, enable the disablePageCaching option to prevent the browser from caching automation scripts.

For more information, see Troubleshooting: Test Actions Fail After Authentication.

You can disable page caching for an individual fixture or test.

CLI: --disable-page-caching
API: runner.run({ disablePageCaching })

disableMultipleWindows

Disables support for multi-window testing.

{
    "disableMultipleWindows": true
}

The disableMultipleWindows option disables support for multi-window testing in Chrome and Firefox. Use this setting if you encounter compatibility issues with your existing tests.

CLI: --disable-multiple-windows
API: runner.run({ disableMultipleWindows })

retryTestPages

If this option is enabled, TestCafe retries failed network requests for web pages visited during tests. The retry functionality is limited to ten tries.

{
    "retryTestPages": true
}

This feature uses Service Workers that require a secure connection. To run TestCafe over a secure connection, setup HTTPS or use the --hostname localhost option.

CLI: --retry-test-pages API: createTestCafe

color

Enables colors in the command line.

{
    "color": true
}

CLI: --color

noColor

Disables colors in the command line.

{
    "noColor": true
}

CLI: --no-color

userVariables

Specifies user variables and their values.

Follow the step below to add user variables and use them in a test:

  1. Add pairs of variable names and values to the userVariables option within the testcaferc.json file.

  2. Import the userVariables from the testcafe module to the test.

.testcaferc.json:

{
  "userVariables": {
    "url": "http://devexpress.github.io/testcafe/example",
  }
}

test.js:

import { userVariables } from 'testcafe';

fixture `Test user variables`
    .page(userVariables.url);

test('Type text', async t => {
    await t
        .typeText('#developer-name', 'John Smith')
        .click('#submit-button');
});

disableHttp2

Disables support for HTTP/2 requests.

{
    "disableHttp2": true
}

CLI: --disable-http2