When you write functional tests, sooner or later you face the need to debug them. In this article, I’ll review everything TestCafe offers to facilitate this daily routine task.

TestCafe test code is executed on the server. Therefore, first, we should have a way to debug server code. User actions are emulated in the browser. That is why we also should have the capability to check what is happening on the client side.

I’ll further explain how you can do server and client debugging with TestCafe. I’ll also describe a few settings that are useful for debugging.

Server debugging

Starting with version v6.3.0, Node.js allows for debugging applications in Chrome Developer Tools. If you have Chrome and an appropriate version of Node.js installed on your machine, you can easily debug test code. To do this, add special flags --inspect and --debug-brk to test run command.

testcafe --inspect --debug-brk chrome ./tests

Also, put the debugger; keyword in test code where you want to stop.

After this command is executed, a special debugging URL will appear in the console.

Open this URL in a new Chrome browser instance and you’ll see standard Developer Tools. Debugger will stop test execution at the first line to give you time to open Developer Tools before the test starts. Click the “Resume script execution” button or press F5 to continue. Text execution will pause at the debugger; keyword. You can use all the Developer Tools features to debug your tests as you would do with a web page.

Client debugging

To debug client test code, use a special action — t.debug() .

When test execution reaches this action, it pauses so that you can open browser’s developer tools and check the expected web page state, DOM elements location, their CSS styles. In the footer, you’ll find buttons that allow you to continue test execution or step to the next test action.

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

TestCafe logs points in code where the debugger stopped.

Useful options for the debugging

TestCafe includes a few features helpful when you need to find the cause of issues in your tests.

Screenshots — you can explicitly specify places in your test where screenshots should be taken. Use the t.takeScreenshot([path]) action for this. You can also turn on the --screenshots-on-fails CLI option,

testcafe chrome ./tests --screenshots ./screenshots --screenshots-on-fails

This option enables TestCafe to take a screenshot automatically when a test fails. Analyzing these screenshots helps save much time on debugging and allows you to localize the reason of issue earlier.

Test speed — use this option to change testing speed. By default, tests are executed at full speed with minimum delays between actions and assertions. This makes it hard to identify problems visually when running the test. To slow down the test, use the --speed CLI flag. Its value changes from 1 to 0.01 .

testcafe chrome ./tests --speed 0.1

When you slow down the test, you can monitor test execution more easily and see when the test behavior differs from the one that’s expected.