JavaScript and TypeScript library

The @testorim/cli package (version 0.4.0 and later) is also a JavaScript and TypeScript library: a test suite can run a Testorim test and gate on the verdict. It ships its own types, has no dependencies and needs Node 20 or newer.

npm install --save-dev @testorim/cli

Create an API key in Testorim under Settings → API keys and put it in TESTORIM_API_KEY. See Authentication for what a key may change.

From code

import { Testorim } from "@testorim/cli";

const testorim = new Testorim(); // reads TESTORIM_API_KEY

const run = await testorim.runTest(
  "Shop", // a project's name, address or id
  "Add the Blue Top to the cart, open the cart and check that it shows 1 item.",
);
console.log(run.summary());
run.assertPassed(); // throws TestorimRunFailed unless the verdict is passed

runTest starts the run and waits for the verdict (up to 10 minutes by default). Other calls:

await testorim.projects();                                   // the workspace's projects
await testorim.tests("Shop");                                // a project's saved tests
await testorim.runSaved("Checkout", { project: "Shop" });    // replay a saved test by name or id
await testorim.runTest("Shop", "...", { baseUrl: "https://pr-42.preview.example.com" });
await testorim.runTest("Shop", "Sign in with a wrong password and check that an error is shown.", { expectFailure: true });
const started = await testorim.runTest("Shop", "...", { wait: false }); // start without waiting
await testorim.waitFor(started.id);                          // then wait
await testorim.cancel(started.id);

A run has a verdict (passed, failed or needs_review; null while it runs or when cancelled), the step counts, the written report, failedSteps (each with the reason and blame: app, test, unsupported or internal), the run’s url, and links to the video, Playwright trace and final screenshot, which expire an hour after they were read. summary() leaves those links out because it often lands in CI logs.

In Playwright Test

import { test } from "@playwright/test";
import { Testorim } from "@testorim/cli";

const testorim = new Testorim();

test("checkout works", async () => {
  test.setTimeout(11 * 60_000); // a run takes minutes; the default is 30 seconds
  const run = await testorim.runSaved("Checkout", { project: "Shop" });
  run.assertPassed();
});

A failed run fails the test with its summary:

TestorimRunFailed: Verdict: FAILED (1 passed, 1 failed, 1 skipped, 41s)
Run: https://app.testorim.com/runs/...
Failed step 2: click "Create account": The page showed Something went wrong [the app did not behave as described]

In Vitest and Jest

Both work the same way; give the test a longer timeout as the third argument: test("checkout works", async () => { ... }, 11 * 60_000). The package is ESM, so run Jest with its ESM support (NODE_OPTIONS=--experimental-vm-modules npx jest). A CommonJS project can require("@testorim/cli") on Node 20.19 or newer and 22.12 or newer.

Errors

Every error derives from TestorimError, and each is exported:

Error	When
`AuthenticationError`	401: the key is missing, wrong or revoked.
`RefusedError`	402, 429 or 503: Testorim will not start the run now. `code` and `retryable` say why and whether waiting helps; see API errors.
`NotFoundError`	No project or saved test matches, or it is in another workspace.
`TestorimUnreachable`	The API could not be reached.
`TestorimRunFailed`	`assertPassed()` on a run that did not pass.
`TestorimTimeout`	A wait with `raiseOnTimeout: true` ran out.

The client never retries a trigger by itself, because a retried trigger is a second run. If your workspace lives on another host, pass apiUrl or set TESTORIM_API_URL. The full reference is in the package README.

Limits

The site must be reachable from the internet: Testorim’s browsers refuse localhost and private addresses.
Every run counts against your plan, whichever tool started it.
The same package is the CLI and the MCP server for coding agents. Working in Python? See Python and pytest.

​From code

​In Playwright Test

​In Vitest and Jest

​Errors

​Limits

From code

In Playwright Test

In Vitest and Jest

Errors

Limits