Get started

Installation

Introduction

CSTesting is a simple, extensible Node.js testing framework. You get a test runner and assertions (like a minimal Jest/Mocha), CDP-based browser automation (Chrome/Chromium), and config-driven tests—define and run full flows from a single config file and get one test case with an HTML report. No Playwright or Cypress required for core usage.

You will learn

  • How to install CSTesting
  • What gets installed and scaffolded
  • How to run the example test
  • How to open the HTML test report

Installing CSTesting

Get started with a Playwright-style project wizard, or add CSTesting to an existing project.

New project (recommended)

Create a folder, initialize npm, then run the CSTesting wizard. This is the same as npm create cstesting@latest.

mkdir my-tests
cd my-tests
npm init -y
npm init cstesting@latest

The wizard prompts you for:

  • Language: TypeScript or JavaScript (default: TypeScript)
  • Tests folder: where to put end-to-end tests (default: tests, or e2e if tests already exists)
  • GitHub Actions workflow: add a CI workflow (default: yes)
  • Verify Chrome: check that Chrome/Edge is available for browser tests (default: yes)

When setup finishes, run npm test to execute the sample test.

Using yarn or pnpm

yarn create cstesting@latest    # or pnpm create cstesting@latest

Existing project

Install the package, then run the same interactive wizard:

npm install cstesting
npx cstesting init
# or
npx cst init

npm install cstesting alone does not scaffold files — run npx cstesting init (or use npm init cstesting@latest in a new folder) to create tests and configure the project.

Install from local clone

If you are developing from the repo at C:\CSTesting-Nodejs (or another local path), install the package from that folder and run the wizard:

npm install C:\CSTesting-Nodejs
npx cstesting init

What's Installed

After the wizard completes, your project typically looks like this:

package.json              # cstesting dependency + "test" script
package-lock.json         # or yarn.lock / pnpm-lock.yaml
tests/                    # or e2e/ (your chosen folder)
  sample.test.ts          # or sample.test.js (JavaScript)
tsconfig.json             # TypeScript only
.github/workflows/
  cstesting.yml           # if you chose GitHub Actions
  • tests/ (or your chosen folder) — Sample test file (*.test.js, *.test.ts, *.spec.js, *.spec.ts).
  • package.json — Adds cstesting, sets "test": "cstesting tests/" (or your folder), and runs npm install.
  • TypeScript — When you choose TypeScript, the wizard adds typescript, ts-node, and @types/node as dev dependencies and writes tsconfig.json. See TypeScript for details.
  • Page Object Model — Not part of the default scaffold. Create a pages/ folder yourself when you want POM; see Page Object Model (POM).

Running the Example Test

By default, tests run headless in your project directory. The CLI discovers all matching test files and prints results in the terminal.

npx cstesting
# or
npx cstesting tests/
# or use the short alias
npx cst tests/

Tips:

  • Run a single file: npx cstesting tests/home.test.js
  • Run with a pattern: npx cstesting "**/*.test.js"
  • Run config-driven tests: npx cstesting run login.conf or npx cstesting login.conf

See the main Config-driven tests guide for filtering by tags, headed mode, and config files.

HTML Test Report

After a test run, an HTML report is written to the report/ folder. The CLI prints the path (e.g. report/report.html). Open that file in your browser to see:

  • Summary (passed / failed / skipped)
  • Tests grouped by file
  • Expandable steps and errors per test
# After running tests, open the report (path is shown in the terminal)
# Example: report/report.html

No separate "show report" command is required—just open the printed path in your browser.

Re-running Setup (init)

If you installed cstesting without running the wizard (e.g. CI or a plain npm install), or want to scaffold again:

npx cstesting init
# or
npx cst init

You will be asked again for language, tests folder, GitHub Actions, and Chrome verification. Existing files are not overwritten by the templates; you may need to adjust or merge manually if you re-run on an existing project.

Updating CSTesting

Update to the latest version:

npm install cstesting@latest
# or
yarn add cstesting@latest
# or
pnpm add cstesting@latest

Check the installed version:

npx cstesting --version
# or
npx cst --version

System requirements

  • Node.js: 16.x or later (see engines in package.json).
  • Browsers: Chrome or Chromium for CDP-based automation (used by the built-in browser support). Optional Playwright can be used if installed in the project.
  • OS: Windows, macOS, or Linux.

Next steps

  • Add more tests under your tests folder (e.g. tests/ or e2e/).
  • Organize selectors with the Page Object Model (POM) pattern when your suite grows.
  • Run config-driven tests from a .conf file: see Config-driven tests.
  • Use recording to generate tests: npx cstesting record --output tests/flow.test.js.
Next Writing tests »