RunCommandOptions
Options for runCommand.
Extends RunOptions with the CLI-root state runCommand() mirrors, following the way CLIRunOptions extends CLIExecuteOptions with the fields only that layer needs.
- Import:
@kjanat/dreamcli/testkit - Export kind: interface
- Declared in:
src/core/testkit/index.ts - Source link:
src/core/testkit/index.ts:52
Signatures
interface RunCommandOptions extends RunOptions {}Members
Properties
builtins
Which built-in flags the harness mirrors, matching the CLI the command is registered on.
A command that owns a released built-in (cli(...).builtins({ json: 'off' }) plus a json flag) must be tested with the same setting, otherwise the harness strips the token before parse() sees it.
builtins?: BuiltinsConfig;env
Environment variables for flag and arg resolution.
Inputs with .env('VAR') configured resolve from this record when CLI and stdin produce nothing (CLI → stdin → env → config → prompt → default).
env?: Readonly<Record<string, string | undefined>>;config
Configuration object for flag and arg resolution.
Inputs with .config('path') configured resolve from this record when CLI, stdin, and env produce nothing (CLI → stdin → env → config → prompt → default). Config is plain JSON, so file loading is the caller's responsibility.
config?: Readonly<Record<string, unknown>>;stdinData
Full stdin contents for flags and args configured with .stdin().
Lets tests inject piped input without a runtime adapter.
stdinData?: string | null;prompter
Prompt engine for interactive flag and arg resolution.
When provided, inputs with .prompt() configured that have no value after CLI, stdin, env, and config resolution are prompted interactively.
When absent (and answers is also absent), prompting is skipped and resolution falls through to default/required.
Takes precedence over answers when both are provided.
prompter?: PromptEngine;answers
Pre-configured prompt answers for testing convenience.
When provided, a test prompter is created from these answers via createTestPrompter(answers). Each entry is consumed in order — use PROMPT_CANCEL to simulate cancellation.
Ignored when an explicit prompter is provided.
answers?: readonly TestAnswer[];stat
Filesystem probe for flag.path() and arg.path() checks: reports what exists at a path ('file', 'directory', or null for nothing).
CLIBuilder.run() supplies the runtime adapter's probe automatically. When absent (process-free .execute() / runCommand() without an override), path checks are skipped and each skipped input is listed in RunResult.skippedPathChecks; set RunOptions.pathChecks to 'strict' to fail instead.
stat?: { (path: string): Promise<"file" | "directory" | null>; };mkdir
Recursive directory creation for flag.path() and arg.path() create checks.
CLIBuilder.run() supplies the runtime adapter's implementation automatically. When absent, missing paths are not created: the existence rules decide instead, and the input is listed in RunResult.skippedPathChecks with missing: 'mkdir'.
mkdir?: { (path: string): Promise<void>; };pathChecks
What happens to a declared filesystem check that cannot run because stat (or mkdir for create) was not supplied.
'lenient'— skip the check and record it inRunResult.skippedPathChecks; the command still runs, which keeps parser and action tests off the host filesystem.'strict'— fail with aCLIErrorof code'PATH_CHECK_SKIPPED'(exit code1) naming every input whose check did not run, so a passing test proves each declaredmustExist,type, andcreatecheck was exercised.
Only inputs that resolved a path value count. CLIBuilder.run() always supplies the adapter's filesystem, so this matters to .execute() and runCommand().
pathChecks?: "lenient" | "strict";envPrefix
Environment namespace prepended to every relative .env() binding, the same way CLIBuilder.envPrefix() applies one CLI-wide.
.execute() and .run() default it to the CLI's own prefix, and a value here wins. Pass it to runCommand() to test a command under the namespace its CLI declares; without it a command reads its env names as written.
envPrefix?: string;verbosity
Verbosity level for the output channel.
verbosity?: Verbosity;jsonMode
Enable JSON output mode.
When true, log and info messages are redirected to stderr so that stdout is reserved exclusively for structured json() output. Framework-rendered errors are emitted as structured JSON to stdout.
jsonMode?: boolean;isTTY
Whether stdout is connected to a TTY.
Handlers can check out.isTTY to decide whether to emit decorative output (spinners, progress bars, ANSI codes). Defaults to false (safe default for tests — non-TTY until proven otherwise).
isTTY?: boolean;terminalSize
Terminal dimensions to expose on the output channel. .run() defaults to the adapter size.
terminalSize?: TerminalSize;color
Explicitly enable or disable ANSI color, overriding automatic selection. Otherwise, env.NO_COLOR disables color and env.FORCE_COLOR enables it unless set to '0'. With neither set, color follows isTTY outside JSON mode.
color?: boolean;help
Help formatting options (width, binName). Used when --help is detected.
help?: HelpOptions;flags
Flag-parsing behavior settings.
caseParity accepts the kebab↔camel counterpart spelling of each flag name/alias (--doThis for do-this, and vice versa). The CLI layer threads cli(name, { flags }) settings here automatically.
flags?: ParseOptions;