CSTesting — TypeScript

Introduction

CSTesting supports TypeScript in two ways: the package ships with type definitions so you get type checking and editor support when writing tests or using the API in TypeScript, and the CLI can run TypeScript test files (.test.ts, .spec.ts) when ts-node is installed in your project.

You can write tests and page objects in TypeScript and run them with npx cstesting without a separate compile step (if you use ts-node), or compile to JavaScript first and run the .js files.

You will learn

• How TypeScript is supported (types, test file discovery)
• How to use CSTesting in a TypeScript project
• How to run TypeScript test files
• Optional: TypeScript config and typing page objects

---

Type definitions

The CSTesting package includes TypeScript declaration files ("types": "dist/index.d.ts" in package.json). When you install CSTesting in a TypeScript project, your editor and the TypeScript compiler use these definitions for:

• Test runner — describe, it, beforeAll, afterAll, beforeEach, afterEach, run, step
• Assertions — expect, AssertionError
• Browser — createBrowser, and types such as BrowserApi, CreateBrowserOptions, LocatorApi, TabHandle, FrameHandle, DialogHandler, StepReporter, SelectOption, SelectOptionOrOptions
• API testing — request, ResponseAssertions, and types ApiResponse, RequestOptions, HttpMethod
• Config — runConfigFile, parseConfigFile, and types ParsedConfig, ConfigStep, ConfigTestCase, RunConfigResult
• Result — RunResult

You get autocomplete, type checking, and inline documentation in VS Code and other editors without extra setup.

---

Using CSTesting in a TypeScript project

Install dependencies

npm install cstesting
npm install -D typescript ts-node

• typescript — For compiling or type checking.
• ts-node — So the CLI can run .test.ts / .spec.ts files on the fly (see Running TypeScript test files).

Import and use

Use ES module import syntax in your test files:

import { describe, it, expect, beforeAll, afterAll, createBrowser } from 'cstesting';
import type { BrowserApi } from 'cstesting';

describe('Example', () => {
  let browser: BrowserApi;

  beforeAll(async () => {
    browser = await createBrowser({ headless: true });
  });

  afterAll(async () => {
    if (browser) await browser.close();
  });

  it('opens example.com', async () => {
    await browser.goto('https://example.com');
    const title = await browser.evaluate("document.title");
    expect(title).toContain('Example');
  });
});

You can import types explicitly when needed:

import type { BrowserApi, LocatorApi, CreateBrowserOptions } from 'cstesting';

---

Test file names

The CLI discovers test files by extension:

Extension	Discovered
.test.js	Yes
.spec.js	Yes
.test.ts	Yes
.spec.ts	Yes

So you can name TypeScript test files e.g. example.test.ts or home.spec.ts and run them with the same commands as JavaScript tests (npx cstesting, npx cstesting tests/, etc.).

---

Running TypeScript test files

Option 1: Use ts-node (no pre-compile)

If ts-node is installed in your project, the CLI will use it when it loads a .ts test file. Run tests as usual:

npx cstesting
npx cstesting tests/
npx cstesting tests/example.test.ts

If you run a .ts file and ts-node is not installed, the CLI prints an error and suggests installing it or compiling to JavaScript first.

Option 2: Compile first, then run .js

Alternatively, compile your TypeScript to JavaScript and run the generated files:

npx tsc
npx cstesting dist/tests/

Or use your existing build script (e.g. npm run build) and point the CLI at the output directory. In that case you do not need ts-node for the test run.

---

TypeScript config (tsconfig.json)

A typical tsconfig.json for a Node project that runs tests with ts-node:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "dist",
    "rootDir": "."
  },
  "include": ["src/**/*", "tests/**/*", "pages/**/*"]
}

• module: "commonjs" — Matches Node and the way the CLI loads test files (require).
• strict — Recommended for better type safety.
• Adjust include so it covers your test and page object paths.

If you use ts-node only for tests and don't need to emit files for them, you can exclude test files from outDir or use a separate tsconfig for building.

---

Typing page objects

You can type the browser parameter in page objects using BrowserApi:

// pages/HomePage.ts
import type { BrowserApi } from 'cstesting';

export class HomePage {
  constructor(private browser: BrowserApi) {}

  get url(): string {
    return 'https://example.com';
  }

  async goto(): Promise<void> {
    await this.browser.goto(this.url);
    await this.browser.waitForLoad();
  }

  async getHeadingText(): Promise<string> {
    const text = await this.browser.evaluate(
      "document.querySelector('h1') ? document.querySelector('h1').textContent : ''"
    );
    return text as string;
  }
}

// tests/home.test.ts
import { describe, it, expect, beforeAll, afterAll, createBrowser } from 'cstesting';
import { HomePage } from '../pages/HomePage';

describe('Home page', () => {
  let browser: Awaited<ReturnType<typeof createBrowser>>;
  let homePage: HomePage;

  beforeAll(async () => {
    browser = await createBrowser({ headless: true });
    homePage = new HomePage(browser);
  });

  afterAll(async () => {
    if (browser) await browser.close();
  });

  it('shows Example Domain', async () => {
    await homePage.goto();
    const heading = await homePage.getHeadingText();
    expect(heading).toContain('Example Domain');
  });
});

Using BrowserApi (and optional return types) keeps page objects and tests type-safe.

---

Summary

Topic	Description
Types	CSTesting ships with dist/index.d.ts; no separate @types package.
Imports	Use import { ... } from 'cstesting' and import type { BrowserApi, ... } from 'cstesting' in TypeScript.
Test files	Use .test.ts or .spec.ts; CLI discovers them like .test.js / .spec.js.
Running .ts	Install ts-node and run npx cstesting; the CLI uses ts-node when loading .ts files. Or compile with tsc and run the .js output.
Page objects	Type the browser as BrowserApi in your page class for full editor and type-check support.