This functionality will help you relive the tests visually as they happened. If trace mode is enabled, Nightwatch captures HTML DOM snapshots after every step. These HTML DOM snapshots can be viewed directly in the HTML report itself. You can even inspect element when a particular step was executed. This will help you debug your tests better.

In this guide you will learn

  1. How to enable DOM history
  2. How to view the DOM history
  3. How to debug using DOM history

Enable DOM history

Enabling DOM history is super simple. Simply run nightwatch tests with the --trace flag.

For E.g.

npx nightwatch --trace


npx nightwatch <path to test file/folder> --trace

When you run your tests with the --trace flag, Nightwatch captures a DOM snapshot of the application under test after each step that can modify the application. Snapshots are not captured for steps that cannot modify the behaviour of the application. For E.g. assertions cannot modify the underlying HTML and hence snapshots are not captured for such steps.

View DOM history

In the previous section you learnt how to enable Nightwatch to capture the HTML DOM snapshots history. In order to debug, the main part is to view & analyse the DOM snapshots history at different steps of the test execution.


  1. Once your test execution completes, simply open up the report in the browser by copy pasting the report file path
  2. Select a failed test/hook from the left panel
  3. Once a test/hook is selected, the steps will be visible under Test Details tab
  4. Click on a step to see how the DOM snapshot looks like just after the step was executed

DOM History

Click on different steps will update the HTML DOM snapshot in the right panel so that it can be inspected using devtools.

Debug using DOM history

Let's understand how this can be useful while debugging test errors. When a test errors out, the report will exactly pinpoint which step in the test has failed. Inorder to debug, we recomomend that you inspect the step that failed as well as steps before that.

Since the HTML snapshots are embedded in the report in the browser itself, you can easily inspect the snapshots using devtools as shown below

Inspect element with DOM history

Inspecting the DOM snapshot in the previous steps can help with the debugging of the issue. If the previous snapshot is different from what you were expecting, the previous steps might need modification. If the previous snapshot looks correct, you can

  1. verify if the selectors used are accurate as per the DOM snapshot
  2. inspect the state of the element you are interacting with to understand if the interactibility is hindered in any way or not

Happy debugging!