Command-line options
Everything after -- in dub test :pkg -- <options> goes to the runner.
Selection and output
| Option | Description |
|---|---|
-i, --include | Run only tests whose fullName name matches the regular expression |
-e, --exclude | Skip tests whose fullName name matches; combines with -i (a test must match -i and not match -e) |
-v, --verbose | Durations, [file:line] locations, full stack traces |
-t, --threads | Worker threads; 0 (default) auto-detects, 1 runs single-threaded |
--no-colours | Disable colored output (also honors $NO_COLOR and non-tty stdout) |
-l, --list | List discovered tests with @ctfe/@benchmark/@betterC/@wasm markers |
--self-test | Also run the test runner's own unittests |
-h, --help | Option summary |
Modes
| Option | Description |
|---|---|
| (none) | Run regular tests in parallel; evaluate selected @ctfe tests via CTFE. On an interactive stdout a polled progress line (⠹ 12/40 (1.2s)) redraws beneath the streaming result lines and is erased before the summary — suppressed by the same rules as the --bench spinner |
--bench | Measure @benchmark tests (serial). Cases are registered from all bench bodies, then scheduled and measured grouped by their streaming key — the --group-by group, else the source test — with timing and metric columns aligned on the decimal point and consecutive tables sharing their column geometry. On an interactive stdout each group's table ticks live: it repaints in place, growing a row per measured case with a dim ⠹ name │ measuring… row for the case in flight, then graduates into scrollback when the group completes. With stdout redirected but stderr on the terminal, a one-line spinner (⠹ 12/40 name) animates on stderr instead; both displays obey the same suppression rules (piped, non-tty, --no-colours, $NO_COLOR, TERM=dumb), and a piped run prints each table once, byte-stable |
--perf | With --bench: add hardware perf counters per benchmark (Linux perf_event) — IPC, instructions/iter, cache/branch miss rates |
--syscalls[=LIST] | With --bench: count syscalls/iteration (perf tracepoints); bare = total column, =futex,… adds one each. Needs readable tracefs + perf_event_paranoid ≤ 1 (usually root) |
--metrics=LIST | With --bench: choose metric columns (comma list; glob with *; all = every available; ?/help = list). Default: standard. Naming a perf metric (or all) opens the --perf pass automatically, and naming syscalls/syscalls:<name> opens the --syscalls pass; a selector that matches nothing warns on stderr |
--list-metrics | List the available metric columns (name, class, source) and exit. Works with or without --bench |
--sort-by=KEY | With --bench: sort rows by name or a metric column name (ascending; sc:<name> and syscalls:<name> are the same column). Default: median/iter. Applied within --group-by groups; error rows always sort last. An unknown column name warns on stderr and leaves the default order |
--bench-json=FILE | With --bench: also write the results as JSON — every row in measurement order (error rows included) plus a meta block (host, compiler, effective knobs), with metrics keyed by catalog names. Deterministic; for committed baseline snapshots. A write failure fails the run |
--bench-min-time=MS | With --bench: per-case measurement budget in milliseconds (default 5) — per-call benchCase rows: minimum total measured time; batched (benchIter/whole-body): target per sample. Inert for pinned @benchmark(iterations: N) |
--group-by=KEYS | With --bench: split the report into one table per group of the given case label keys (comma-separated or repeated; each titled benchmark: <group> over an implementation column listing the row name). E.g. =dataset,operation. =all groups by every label key; =list prints the available keys and exits |
--better-c | Extract @betterC tests, compile with -betterC, run without druntime |
--wasm | Extract @wasm tests, cross-compile to wasm32, run in a wasm runtime |
--ctfe-trace FILE | Evaluate @ctfe tests under LDC -ftime-trace and report per-test cost |
The run modes are mutually exclusive: combining --bench, --ctfe-trace, and --better-c/--wasm is an error (--better-c with --wasm is fine — one extraction family), while --list/--list-metrics are queries that win over any mode. Under --bench, an assert-enabled (debug) build prints a warning on stderr — dub's stock unittest build type is one; real numbers need an optimized unittest buildType.
@ctfe tests are evaluated by a probe program compiled with -o- -unittest (semantic analysis only) after -i/-e filtering, so only the selected tests execute, and --help/--list never evaluate any — even ones that would fail. See Write compile-time tests.
@ctfe / --better-c / --wasm toolchain options
| Option | Description |
|---|---|
--compiler DC | D compiler to use (default: $DC, then ldc2, dmd from PATH) |
-I, --import-path DIR | Extra import path (repeatable) |
--include-import PATTERN | Compile matching imported modules in (-i=PATTERN; repeatable) |
--keep | Keep the generated program files and print their location |
Skipped tests
A test may skip itself at runtime with skipTest("reason") (see Skip tests at runtime): it renders as a yellow ⊘ line with the reason, adds a , N skipped segment to the summary, and never fails the run. Under --bench, a case-level skip is a yellow row in its table.
Exit status
0 when everything passed or was skipped (skipTest, or a toolchain-missing mode); non-zero otherwise.