Quick start

This guide takes you from an empty project to a test that runs. You need Node.js 24.12 or later, a web app to test, and Chrome, Edge or Chromium.

Set up a project #Link to Set up a project

1. 1

   Step 1: Add the package

   $ npm install -D @rehearsal-labs/retest typescript @types/node

   TypeScript is there to check types. Retest loads .ts files with the TypeScript support built into Node.js.

2. 2

   Step 2: Write the starter files

   $ npx retest init

   init writes retest.config.ts, tests/example.retest.ts and tests/tsconfig.json. It adds the test:e2e and typecheck:e2e scripts to package.json, and .retest/ to .gitignore. It never overwrites a file.

   At a terminal it asks for your app's address, how to start it and a browser. Give answers as flags, and --yes takes the default for the rest:

   $ npx retest init --app web=http://localhost:3000 --browser chrome --yes

3. 3

   Step 3: Check the setup

   $ npx retest doctor

   doctor launches each browser once and checks that your app answers. Each problem it finds comes with its fix.

The config #Link to The config

With the flags above, init writes a config like this one. web is the app's name, and chrome() runs the tests in Google Chrome. When package.json has a dev or start script, init also adds a start line, so Retest can start your app itself.

import { chrome, defineConfig } from '@rehearsal-labs/retest'const config = defineConfig({  apps: {    web: chrome({      baseUrl: 'http://localhost:3000',    }),  },})export default config// Lets every test file see your app names, secrets, test ids and tags.declare module '@rehearsal-labs/retest' {  interface Register {    config: typeof config  }}

The declare module block tells TypeScript your app names, so a typo is a type error. Types and imports explains it.

Your first test #Link to Your first test

This is the test init writes. It opens the home page and checks that the page has a main region.

import { expect, test } from '@rehearsal-labs/retest'test('shows the home page', async ({ page }) => {  await page.goto('/')  await expect(page.getByRole('main')).toBeVisible()})

page.goto('/') opens the path on the app's baseUrl. The check looks at the page again and again until the region is visible, for up to five seconds.

Run it #Link to Run it

$ npx retest run

Retest runs every .retest.ts file under the folder. It prints each test as it ends, then a summary and the exit code. The exit code is 0 when every test passed.

Read a failure #Link to Read a failure

When a check fails, Retest prints a card. It shows what the check expected, what the page showed and the line where the test stopped.

  ✗ tests/tasks.retest.ts › saves a task  5.6s    Check failed     toHaveText    Locator          getByTestId('saved-task')    Page             http://127.0.0.1:4173/    - Expected       "Release checklist"    + Received       "Saving…"    Compared         whole text, ends trimmed, each run of spaces or line breaks read as one space    Waited           5s for toHaveText, looked 14 times, limit 5s    tests/tasks.retest.ts:7:3      5 │   await page.getByTestId('task-title').fill('Release checklist')      6 │   await page.getByTestId('save-task').click()    › 7 │   await expect(page.getByTestId('saved-task')).toHaveText('Release checklist')      8 │ })    Screenshot       .retest/runs/<time>/artifacts/…/screenshot-failure-1.png    Rerun            npx retest run tests/tasks.retest.ts:3    Inspect          npx retest inspect .retest/runs/<time> --test "tests/tasks.retest.ts > saves a task"

The command after Rerun runs that one test again. The command after Inspect shows every step the test took. Read a failure explains each line.

Next steps #Link to Next steps

• Write a test with suites, steps and hooks.
• Find elements the way a person does, with Locators.
• Add apps and browsers in the Configuration.