interface UserRunOptions

Everything a run can be told to do. Every field is optional: run() with no arguments runs the project exactly as a bare qunitx would, minus the printing.

Two things differ from the command line, both because they cannot be typed into a shell: plugins takes live esbuild plugin objects, and cwd picks the project.

const options: UserRunOptions = { inputs: ['test/'], filter: 'Cart', coverage: true };
options.reporter; // undefined — nothing is printed unless you ask for it

Properties

optional
inputs: string[]

Files, directories, globs, or file.ts#34 line targets — the same grammar as the command line's positional arguments. Defaults to package.json#qunitx.inputs.

optional
cwd: string

Directory the project root and relative inputs resolve against. Defaults to process.cwd().

optional
filter: string

Run only tests whose "Module: test name" matches. QUnit's own semantics: case-insensitive substring, /regex/, /regex/i, or a leading ! to invert.

optional
browser: "chromium" | "firefox" | "webkit"

Browser engine. Defaults to chromium, the only one that can collect coverage.

optional
timeout: number

Milliseconds a single test may take before the run is declared stalled. Defaults to 20000.

optional
failFast: boolean

Stop the run at the first failing test.

optional
onlyFailed: boolean

Run only the files that failed last time, from the persistent failure cache.

optional
changedSince: string

Run only files whose transitive imports changed since this git ref ('HEAD' for uncommitted).

optional
coverage: boolean | { formats?: Array<"lcov" | "html">; }

Collect V8 line coverage (chromium only). formats additionally writes lcov/html artifacts.

optional
junit: boolean | string

Write a JUnit XML report. true writes <output>/junit.xml; a string is a path.

Print the run with ONE reporter: a built-in name ('tap', 'spec', 'dot', 'github'), your own Reporter, or false. The same spelling as the CLI's --reporter.

Omitted means nothing is printed — the result value is the output.

optional
reporters: ReadonlyArray<ReporterOption>

Print the run with SEVERAL. Mutually exclusive with UserRunOptions.reporter: pass reporter for one, reporters for many, and validate rejects both at once.

optional
console: Console

Where the run's text goes. Defaults to the process streams when a reporter is NAMED, and to silentConsole otherwise — so a programmatic run prints nothing unless it was asked to.

Set it to capture the built-in reporters' output, which is the only way to reach it: console: streamConsole(myBuffer).

optional
output: string

Directory for the compiled bundle and HTML output. Defaults to 'tmp'.

optional
port: number

Port for the local test server. Defaults to 1234, incrementing on conflict.

optional
extensions: string[]

File extensions treated as test files. Defaults to ['js', 'ts', 'jsx', 'tsx'].

optional
html: string[]

HTML fixture files to wrap the bundle in, relative to the project root.

optional
before: string | false

Path to a module run before the tests; it receives the resolved config.

optional
after: string | false

Path to a module run after the tests; it receives the run's counters.

optional
plugins: EsbuildPlugin[]

esbuild plugins for the test bundle — live objects, not specifiers.

optional
debug: boolean

Forward every page console call and print the server URL.

optional
open: boolean | string

Open the output in a browser: true for the default, a string to name a binary.

Cancels the run when it fires.

Cancellation here means "stop and answer", not "throw": the browser drops the rest of its queue and the run resolves with whatever it had, marked aborted: true. The tests that did finish are still on the result, which is the point — a cancelled run that discarded its own findings would be no more useful than one that never started.

An already-aborted signal short-circuits: no browser is launched at all.

Usage

import { type UserRunOptions } from "lib/api/options.ts";