#Rstest instance

Everything on this page is exported from the @rstest/core/api entry of @rstest/core. Use these APIs to create Rstest instances, run or list tests, start watch sessions, and merge blob reports.

import { createRstest } from '@rstest/core/api';

#createRstest

The createRstest function creates and returns an Rstest instance. It resolves config once during instance creation and reuses it as the instance's base config. Options passed to instance methods apply to the current operation without mutating the base config.

cwd defaults to process.cwd() and is the base for resolving a relative config.root; omitting config uses an empty inline config and does not discover a config file in cwd.

createRstest sets RSTEST=true, sets NODE_ENV=test only when it is unset, and never restores either environment variable.

#Example

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest({
  cwd: './packages/app',
  config: {
    include: ['src/**/*.test.ts'],
    reporters: [],
  },
});

const result = await rstest.run();
console.log(result.status);

#Load a config file

Use loadConfig from the main entry to load a config file, then pass its return value ({ content, filePath }) directly as config.

import { loadConfig } from '@rstest/core';
import { createRstest } from '@rstest/core/api';

const loaded = await loadConfig();
const rstest = await createRstest({ config: loaded });

#CreateRstestOptions

• Type:

interface LoadedRstestConfig {
  content: RstestConfig; // Loaded config content.
  filePath: string | null; // Source config file path returned by `loadConfig`, or `null`.
}

interface CreateRstestOptions {
  cwd?: string;
  config?: RstestConfig | LoadedRstestConfig;
  configLoader?: 'auto' | 'jiti' | 'native'; // Loader for configs discovered through `projects`; defaults to `auto`.
}

function createRstest(options?: CreateRstestOptions): Promise<RstestInstance>;

#rstest.context

rstest.context is a read-only object resolved once when the instance is created. You can inspect the resolved state without running tests: use rootPath to map testPath values from results back to the workspace, projects to render or filter a multi-project setup, config to inspect the effective configuration, and version for compatibility checks.

#Example

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest({
  config: {
    projects: [
      {
        name: 'unit',
        include: ['tests/**/*.test.ts'],
      },
    ],
  },
});

console.log(rstest.context.version);
console.log(rstest.context.rootPath);

for (const project of rstest.context.projects) {
  console.log(project.name, project.rootPath);
}

#RstestContext

• Type:

interface ProjectContext {
  name: string; // Project name.
  rootPath: string; // Absolute project root path.
  configFilePath?: string; // Project config file path, when one is associated with the project.
  configFileDependencies?: string[]; // Project config dependencies, including parent project configuration files.
}

interface RstestContext {
  readonly version: string;
  readonly rootPath: string;
  readonly config: Readonly<NormalizedConfig>;
  readonly projects: readonly ProjectContext[];
}

#context.version

The version of @rstest/core currently in use.

• Type: string

#context.rootPath

The absolute root path of the Rstest instance. It is resolved from config.root, using cwd as the base for a relative value.

• Type: string

#context.config

The normalized config of the Rstest instance.

• Type: Readonly<NormalizedConfig>

#context.projects

The resolved project contexts. Without an explicit projects config, the array contains the default project named by config.name ('rstest' by default).

• Type: readonly ProjectContext[]

#rstest.run

rstest.run() runs one test cycle and returns a TestRunResult. It rejects when the run cannot start due to invalid options, configuration or compiler errors; test failures are reported through status without rejecting the promise; see TestRunResult.

#Example

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest({
  config: {
    include: ['src/**/*.test.ts'],
  },
});

const result = await rstest.run({
  filters: ['"src/foo.test.ts"'],
});

console.log(result.status);
console.log(result.summary.tests);

#RunOptions

RunOptions accepts every rstest run flag except config, configLoader, root and trace. See CLI options for the full flag list and packages/core/src/api/types.ts for the exact types.

filters is API-only; the CLI passes filters as positional arguments. It uses case-insensitive substring matching by default. Wrap a filter in matching single or double quotes to match an exact absolute or root-relative path, for example filters: ['"src/foo.test.ts"', 'utils']; quoted and unquoted filters can be mixed. Omit filters to select all files; an explicit empty array selects none.

• Type:

interface RunOptions {
  filters?: string[];
  // ...plus every other `rstest run` flag as an override of the config option
  // of the same name, e.g. `testTimeout`, `coverage`, `reporters`.
}

interface RstestInstance {
  run(options?: RunOptions): Promise<TestRunResult>;
}

#TestRunResult

• Type:

type TestRunStatus = 'pass' | 'fail' | 'error';

interface TestRunResult {
  status: TestRunStatus; // Overall status of the run.
  // Every other field matches the `onTestRunEnd` payload, minus `getSourcemap`.
}

The remaining fields (results, testResults, summary, duration, snapshotSummary, unhandledErrors, coverage, rerunTestPaths) are documented under onTestRunEnd in the Reporter API.

status is 'error' when unhandledErrors is non-empty. It is 'fail' when the run completed with a non-zero exit status, such as from failing tests or test files, a coverage threshold violation, no tests being found without passWithNoTests, or a globalSetup teardown failure. In watch mode, it is also 'fail' while the session still holds a failing test file, even if the current cycle passed. Otherwise, it is 'pass'.

Every entry in unhandledErrors is a plain object that can be serialized to JSON, not an Error instance.

#rstest.watch

rstest.watch() starts a watch session and returns a watcher that closes it.

#Example

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest({
  config: {
    include: ['src/**/*.test.ts'],
  },
});

const watcher = await rstest.watch({
  onResult(result) {
    console.log(
      result.status,
      result.results.map((file) => file.testPath),
      result.rerunTestPaths,
    );
  },
});

await watcher.close();

onResult runs after every completed cycle, including the first. results, summary, and status reflect the whole watch session; rerunTestPaths lists the files executed in the current cycle.

Browser projects are supported. A rerun execution error is delivered through onResult with status: 'error' and does not close the session; startup failures, including a browser globalSetup failure, reject watch().

Errors thrown by onResult are isolated and do not stop the watch session. Calling watcher.close() releases the compiler, workers, file watchers, and pending globalSetup teardown. It is idempotent, repeated calls observe the same result, and it rejects if teardown fails.

rstest.watch() rejects related and changed because they select a fixed file set, while a watch session must pick up newly related tests. Use rstest.run() for these options. related: false and changed: false are ignored.

#WatchOptions

• Type:

interface WatchOptions {
  onResult?: (result: TestRunResult & { rerunTestPaths: string[] }) => void;
}

interface RstestWatcher {
  close(): Promise<void>;
}

interface RstestInstance {
  watch(options?: WatchOptions & RunOptions): Promise<RstestWatcher>;
}

#rstest.listTests

rstest.listTests() collects test files and test declarations without running test bodies.

#Example

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest({
  config: {
    include: ['src/**/*.test.ts'],
  },
});

const tests = await rstest.listTests({
  includeSuites: true,
  includeTaskLocation: true,
});

console.log(tests);

Set filesOnly to skip collecting declarations. includeSuites includes named suites as separate entries. includeTaskLocation from RunOptions adds source locations.

Every entry includes testPath and project. Entries from the implicit default project use config.name ('rstest' by default). Declaration entries include their own name, a suite-prefixed fullName, and parentNames for the hierarchy; file entries omit name and fullName. Skipped and todo declarations are included with runMode set to skip or todo; runnable declarations omit runMode.

Entries are returned in depth-first declaration order. A suite immediately precedes its descendants, and all entries from one file stay contiguous.

rstest.listTests() rejects with ListTestsError when collection fails instead of returning a partial or empty list.

shard applies only when passed explicitly to rstest.listTests(), limiting the result to the selected shard. When it is omitted, every file is listed; a shard value from the instance config is dropped as before.

#ListOptions

• Type:

interface ListOptions {
  filesOnly?: boolean;
  includeSuites?: boolean;
}

interface ListedTest {
  testPath: string; // Path of the test file.
  name?: string; // Declaration's own name; absent for file entries.
  fullName?: string; // Suite-prefixed display name; absent for file entries.
  parentNames?: string[]; // Names of the enclosing suites.
  project: string; // Project name.
  location?: TestLocation; // Source location when requested.
  runMode?: 'skip' | 'todo'; // Skip or todo mode for non-runnable declarations.
  type: 'file' | 'suite' | 'case'; // Entry kind.
}

interface RstestInstance {
  listTests(options?: ListOptions & RunOptions): Promise<ListedTest[]>;
}

#rstest.mergeReports

rstest.mergeReports() merges blob reports and returns the same result model as rstest.run().

It rejects when the operation cannot produce a run result; failures in the merged tests are reported through status without rejecting the promise.

#Example

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest();

const result = await rstest.mergeReports({
  path: './.rstest-reports',
  cleanup: true,
});

console.log(result.status);

path selects the blob-report directory. cleanup removes consumed reports after a successful merge.

#MergeReportsOptions

• Type:

interface MergeReportsOptions {
  path?: string;
  cleanup?: boolean;
}

interface RstestInstance {
  mergeReports(options?: MergeReportsOptions): Promise<TestRunResult>;
}

#runCLI

runCLI runs the Rstest command line in the current process. It parses argv, sets process.exitCode, and installs the CLI's signal handling. Use it when you want the CLI's process behavior; instance methods do not set process.exitCode or install signal handlers.

#Example

import { runCLI } from '@rstest/core/api';

runCLI({
  argv: [...process.argv.slice(0, 2), 'run', 'src/foo.test.ts', '--update'],
});

argv matches the shape of Node.js process.argv and defaults to process.argv: the first two entries are the executable and script paths and are ignored, while the command, filters, and flags start at index 2. This is the same shape used by Rsbuild's and Rspress's runCLI.

See the CLI documentation for all available commands and flags.

#RunCLIOptions

• Type:

interface RunCLIOptions {
  argv?: string[];
}

function runCLI(options?: RunCLIOptions): void;