Get started

Installation

Introduction

CSTesting is a Node.js testing framework that includes:

  • Test runner — describe / it, hooks, assertions (Jest-style)
  • Browser automation — CDP-based (Chrome/Chromium), no extra browser download
  • API testing — Rest-Assured style HTTP requests and status/body assertions
  • Config-driven tests — Run full flows from a simple config file (no code)

You can run unit tests, API tests, and browser tests in one runner, and use config files for quick flows or non-developers.

You will learn

  • How to install CSTesting
  • What gets created when you scaffold
  • How to run tests
  • How to open the HTML test report
  • How to update CSTesting
  • System requirements

Installing CSTesting

Using npm

Add CSTesting to a new or existing Node.js project:

npm install cstesting

No global install needed. Use the CLI via npx:

npx cstesting
npx cst

Scaffold (optional)

Scaffold a Page Object Model structure (pages + tests with sample code):

npx cstesting init
# or
npx cst init

The command does not overwrite existing files; it only creates missing folders and sample files. No prompts.

CSTesting uses the system Chrome or Chromium (via chrome-launcher). There is no separate browser download step.

What's installed

After npm install cstesting and (optionally) npx cstesting init:

  • package.json — Your project and dependencies (plus cstesting).
  • pages/ — Created by init. Page objects (e.g. HomePage.js) that wrap selectors and actions.
  • tests/ — Created by init. Sample test file home.test.js. You can add any *.test.js, *.spec.js, or (with ts-node) *.test.ts / *.spec.ts.

There is no single config file for the test run. Browser options are set per call in code (e.g. createBrowser({ headless: true })) or in config-driven .conf files.

Config-driven flows: You can create .conf files (e.g. login.conf) with steps like goto:url, click=selector, and run them with npx cstesting run login.conf — no test code required.

Running tests

  • Default: Tests run headless (no visible browser window).
  • See the browser: In code use createBrowser({ headless: false }). In a .conf file set headed=true or headless=false.
npx cstesting
npx cstesting tests/
npx cstesting "**/*.test.js"
npx cstesting path/to/file.test.js

Test files run in sequence. Filter by path or pattern: pass a folder, a file path, or a glob.

HTML test report

After each run, CSTesting writes an HTML report to report/report.html (the report/ folder is created if missing). The report lists all tests with pass/fail/skip, duration, and expandable steps (if you use step('name') in tests). Failed tests show the error message and stack.

The report path is printed in the terminal after each run. Open it in your browser:

# Windows
start report\report.html

# macOS
open report/report.html

# Linux
xdg-open report/report.html

Updating CSTesting

Update to the latest version:

npm install cstesting@latest

No separate browser install; CSTesting uses the system Chrome/Chromium.

Check the installed version:

npm list cstesting

System requirements

  • Node.js: 16.0.0 or later (see engines in package.json).
  • OS: Any OS where Node.js and Chrome or Chromium run (Windows, macOS, Linux).
  • Browser: Chrome or Chromium must be installed on the machine. CSTesting launches it via chrome-launcher.
  • Mobile emulation: Not supported.
Next Writing tests »