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 by installing CSTesting using one of the following methods.

Using npm

The steps below either initialize a new project or add CSTesting to an existing one.

1. Create a project (if needed)

mkdir my-tests
cd my-tests
npm init -y

2. Install CSTesting

npm install cstesting

When the install finishes, the setup runs and prompts you to choose:

  • Language: TypeScript or JavaScript (choose 1 or 2)
  • Page Object Model: Create pages + tests scaffold? (yes / no)

Your answers determine what is created: a tests/ folder only (simple sample) or pages/ and tests/ with a Page Object example. You can run the setup again later with npx cstesting init; it will prompt again and create files based on your choices.

Using yarn or pnpm

yarn init -y    # or pnpm init -y
yarn add cstesting   # or pnpm add cstesting

The same prompts appear after install.

What's Installed

CSTesting adds the package to your project and, from your setup choices, creates a scaffold like one of these.

If you chose Page Object Model (yes):

package.json
package-lock.json       # or yarn.lock / pnpm-lock.yaml
pages/
  HomePage.js           # or HomePage.ts (TypeScript)
tests/
  home.test.js          # or home.test.ts (TypeScript)

If you chose no Page Object Model:

package.json
package-lock.json
tests/
  sample.test.js        # or sample.test.ts (TypeScript)
  • pages/ (when POM is yes) — Page objects that wrap selectors and actions.
  • tests/ — Test files (*.test.js, *.test.ts, *.spec.js, *.spec.ts).

For TypeScript, install dev dependencies after setup:

npm install -D typescript ts-node

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 skipped the install prompts (e.g. non-interactive install or CI), or want to scaffold again:

npx cstesting init
# or
npx cst init

You will be asked again for language and Page Object Model; files are created based on your answers. Existing files are not overwritten by the current 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 tests/ or use pages/ for the Page Object Model.
  • 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 »