lib/commands/run.ts - qunitx-cli documentation

Functions

f

realWatchDirectories(

directories: string[],

realpath?: (directory: string) => Promise<string>

): Promise<string[]>

Expands each directory to its real path before anything watches it.

f

run(

entry: string,

settings?: ScriptSettings

): Promise<ScriptOutcome>

Runs a script file in a real browser: bundles it with esbuild, serves it from a localhost origin, evaluates it as a module in the page, and streams its console output to this terminal. Resolves once the script's top level — including any top-level await — settles.

f

setup(

argv?: string[],

cwd?: string

): Task<ScriptInvocation, ScriptConfigFailure>

Reads qunitx run's argv into a target and its settings.

f

suiteHint(

The qunitx <file> line the suite warning suggests, with forward slashes.

f

watchDirectoriesFrom(

inputs: string[],

cwd: string,

pathApi?: Pick<path, "resolve" | "dirname">

): string[]

The directories watch mode should watch, from esbuild's metafile input keys.

f

watchLoop(

directories: string[],

run: () => Promise<void>,

Runs run once, then again on every change to a first-party file in the bundle. Never resolves — watch mode ends when the process is signalled — except to REJECT if the very first run throws, which is a script that never started rather than a bad edit to recover from.

Interfaces

I

ScriptConfig

Everything one qunitx run invocation needs. Its own type rather than the test runner's Config: a script has no test files, no filter, no reporter and no output directory, and threading a script mode through those would make every one of them mean two things.

browser: "chromium" | "firefox" | "webkit"
Engine the script runs in.
console: Console
Where the script's own output goes. processConsole for the CLI.
cwd: string
Directory relative imports and node_modules lookups resolve from.
debug: Args.ParsedFlags["debug"]
--debug: prints the server URL and the page's console, as the bare verb's does.
entry: string
Absolute path of the script to run.
filter: Args.ParsedFlags["filter"]
--filter: narrows a declared suite to matching tests.
junit: Args.ParsedFlags["junit"]
--junit: writes a JUnit XML report for a declared suite.
open: boolean
--open: run in a visible browser window.
port: number
Port the local server binds. Updated in place to the port actually bound.
portExplicit: boolean
True when --port was given, which makes a taken port an error instead of a search.
projectRoot: string
Directory holding the nearest package.json; mapped stack frames print relative to it.
reporter: Args.ParsedFlags["reporter"]
Reporting settings that only matter if the entry turns out to declare tests.
timeout: number | null
--timeout: ms the script may run before it is declared hung, or null for unbounded.
watch: boolean
--watch: re-run on every save instead of exiting after one run.

I

ScriptInvocation

What qunitx run's argv amounts to: the one target, and the settings the flags asked for.

entry: string
The single target, exactly as it was written on the command line.
settings: ScriptSettings
Everything the flags set, including the projectRoot the parse already resolved.

I

ScriptOutcome

What one execution of the script produced.

browserLogs: BrowserLog[]
The script's own console calls and uncaught errors, in emit order and capped at MAX_BROWSER_LOGS — the same shape and the same cap a test run reports, because it is the same thing: a page's console, read over CDP.
browserLogsDropped: number
How many were dropped to stay under the cap. 0 when nothing was.
entry: string
Absolute path of the file that ran, resolved against cwd.
exitCode: number
globalThis.exitCode if the script set one, 1 if it threw, else 0.
tests: RunResult | null
The suite the entry declared, or null when it was a plain script.
value: unknown
The script's export default, or undefined when it has none — or when it had one that could not be handed back, in which case ScriptOutcome.valueProblem says so.
valueProblem: string | null
Why ScriptOutcome.value is undefined despite the script exporting something, or null when there is nothing to explain.

I

ScriptSettings

Everything a caller may set on a script run: the CLI's flags and the API's options, minus argv.

browser: "chromium" | "firefox" | "webkit"
Engine the script runs in. Defaults to chromium.
console: Console
Where the script's own output goes, as test() and watch() take one. Defaults to this process's stdout and stderr; pass silentConsole to capture it from the result instead.
cwd: string
Directory the entry, relative imports and node_modules lookups resolve against.
debug: Args.ParsedFlags["debug"]
Prints the server URL and the page's console, as the bare verb's --debug does.
filter: Args.ParsedFlags["filter"]
Narrows a declared suite to matching tests. Ignored by a plain script.
junit: Args.ParsedFlags["junit"]
Writes a JUnit XML report for a declared suite. Ignored by a plain script.
open: boolean
Run in a visible browser window.
port: number
Port the local server binds. Defaults to 1234.
portExplicit: boolean
True when a port was named explicitly, which makes a taken one an error rather than a search.
projectRoot: string
Skips the package.json walk when the caller has already done it.
reporter: Args.ParsedFlags["reporter"]
Stdout format when the entry turns out to be a suite. Ignored by a plain script, which has no report to format — its own output IS the output.
timeout: number | null
Ms the script may run before it is declared hung; null (the default) is unbounded.
watch: boolean
Re-run on every save instead of exiting after one run.