Running and debugging tests

Introduction

With CSTesting you can run a single test file, a folder of tests, or all tests matching a pattern. Tests run from the command line and execute in headless mode by default (no browser window). Results appear in the terminal, and an HTML report is written after each run. To see the browser while tests run, use headed mode in your test code or in a config file — there is no CLI flag. CSTesting does not include a built-in UI mode or inspector; you debug with Node.js tools (e.g. VS Code debugger, console.log) and optionally run in headed mode to watch the browser.

You will learn

• How to run tests from the command line
• How to debug tests
• How to open the HTML test report

---

Running tests

Command line

Run tests with the cstesting command (or the short alias cst). This discovers test files (.test.js, .spec.js, .test.ts, .spec.ts) and runs them. Results appear in the terminal. Tests run in headless mode by default (no browser window opens).

npx cstesting

With no arguments, CSTesting looks for files matching **/*.test.js in the current directory (and subdirectories, excluding node_modules and dist).

Run in headed mode

CSTesting does not have a --headed CLI flag. To see the browser while tests run, set headed mode in your test code or in a config file.

In code: pass headless: false when creating the browser:

browser = await createBrowser({ headless: false });

In a config file: set headed=true or headless=false in your .conf file, then run:

npx cstesting run login.conf

Run specific tests

Single test file: pass the file path.

npx cstesting tests/landing-page.test.js
npx cstesting example/apitesting.test.js

Folder: pass a directory. All test files in that directory (and subdirectories) are run.

npx cstesting tests/
npx cstesting tests/todo-page/

Pattern: pass a glob to match multiple files.

npx cstesting "**/*.test.js"
npx cstesting "**/login*.test.js"

Test files run one after another (sequential). There is no --project flag — CSTesting uses a single browser engine (Chrome/Chromium).

Run config-driven tests

To run a flow defined in a config file (no test code):

npx cstesting run login.conf
# or
npx cstesting login.conf

Scaffold and init

Scaffold the Page Object Model structure (pages + tests):

npx cstesting init
npx cst init

---

Debugging tests

CSTesting runs in Node.js, so you can debug it with standard Node tools: console.log, your IDE's debugger, or the VS Code debugger.

Use console.log

Add console.log() in your test to inspect values:

it('debug with log', async () => {
  await browser.goto('https://example.com');
  const html = await browser.content();
  console.log('Page length:', html.length);
  expect(html).toContain('Example');
});

Debug in VS Code (or another IDE)

1. Set breakpoints in your test file (e.g. click in the gutter next to a line).
2. Create a launch configuration that runs the CSTesting CLI with Node's inspector.

Example .vscode/launch.json to run the current test file:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug CSTesting",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/cstesting/dist/cli.js",
      "args": ["${relativeFile}"],
      "cwd": "${workspaceFolder}"
    }
  ]
}

Replace cstesting with the path to your local build if you are developing CSTesting itself (e.g. "program": "${workspaceFolder}/dist/cli.js"). Start debugging with F5 or the Run and Debug view; execution will stop at your breakpoints.

Run in headed mode to watch

To see what the browser is doing step by step, run tests with a visible browser. In your test file, use createBrowser({ headless: false }). You can also add a delay (e.g. await browser.sleep(5000)) or a breakpoint so the browser stays open while you inspect the page.

CSTesting does not include a built-in UI mode or a Playwright-style inspector. For step-by-step tracing and locator tools, use your IDE debugger and headed mode.

---

Test reports

After each run, CSTesting writes an HTML report to report/report.html (the report/ folder is created if it does not exist). The report is not opened automatically. The path is printed in the terminal at the end of the run.

Open the HTML report

Open the report file in your browser:

# Windows
start report\report.html

# macOS
open report/report.html

# Linux
xdg-open report/report.html

Or open report/report.html from your file explorer or IDE.

What the report shows

The HTML report lists all tests with:

• Status — Passed, failed, or skipped
• Duration — Time per test
• Steps — If you use step('name') in your tests, each test row can be expanded to show the list of steps
• Errors — For failed tests, the error message and stack trace are shown

You can open any test row to see its steps and error details. There is no built-in filter by "browser" (CSTesting runs on a single browser) or by "flaky"; you see one report per run with all tests from that run.