Debug Tests

TestCafe allows you to debug server-side test code and test behavior on the client.

Debug Test Code

You can debug test code in Chrome Developer Tools and popular IDEs. See the following recipes for details.

Debug Selectors

Use the Visual Selector Debugger to interactively debug and generate Selector queries.

Enter a Selector query

Client-Side Debugging

TestCafe provides the t.debug method that pauses the test and allows you to debug it with the browser’s developer tools.

You can also use the --debug-mode command line option to pause the test before the first action or assertion.

The footer displays buttons that allow you to continue the test, or skip to the next test action or assertion.

Page Footer when Debugging on a Client


The debugger does not stop at creating and resolving the selectors and client functions.

TestCafe logs points in code where the debugger stopped.

Logging Debugger Breakpoints


fixture `Debugger example`
    .page ``;

test('Debugger', async t => {
    await t
        .setNativeDialogHandler(() => true)

Options Useful for Debugging

TestCafe includes features that help you locate the cause of issues in your tests.


You can specify that a screenshot should be taken in a particular place in a test using the t.takeScreenshot action.

fixture `My fixture`
    .page ``;

test('My test', async t => {
    await t
        .setNativeDialogHandler(() => true)

You can also specify the takeOnFails option to automatically take a screenshot when a test fails.

testcafe chrome ./my-tests --screenshots path=./screenshots,takeOnFails=true

Analyzing these screenshots reduces debugging time and allows you to determine the reason of issues earlier.

Test Speed

TestCafe provides the capability to change test speed. Tests are executed at full speed with minimum delays between actions and assertions, which can make it hard to identify problems when a test is running.

To slow down the test, use the --speed CLI flag. You can use values from 1 to 0.01.

testcafe chrome ./my-tests --speed 0.1

When tests run slower, you can monitor test execution and notice when the test’s behavior differs from what is expected.

Skip JavaScript errors

Main article: Skip JavaScript Errors

TestCafe tests fail when a page yields a JavaScript error. Usually, errors are signs of malfunction that warrant action. However, in some cases third-party modules yield errors that the user cannot fix.

If you enable the skipJsErrors option, TestCafe deliberately ignores JavaScript errors and lets tests proceed.

  • Use the t.skipJsErrors action to ignore JavaScript errors at specific points in the test.

For each of the methods above, you can define the following options:

  • The pageUrl option filters errors by page URL.
  • The message option filters errors by message.
  • The stack option filters errors by call stack.