Invocation, options and results
링크topaz test
topaz test [entry]
입력
Accept zero or one entry operand, the listed compiler and package selectors, and program arguments after -. A selected entry with - naming a package must be an admitted file under that package root.
With no entry, test the package entry. Reject standalone -, unsupported JSON output, export inspection, profile selectors, and invalid program input signatures before execution.
옵션과 충돌
| 옵션 | 기본값 | 계약 | 충돌 |
|---|---|---|---|
--compiler rust|self | self | compiler selector (default self); rust selects the reference compiler Also rejects combination with --producer, --self-source. | 없음 |
--locked | false | Verify topaz.lock before compiling the selected package. | 없음 |
--verbose | false | Reports the selected compiler and whether it was explicit or the default. For | 없음 |
--root <dir> | entry directory; . in package mode | The explicit source root or package root for this invocation. | 없음 |
--language-version <5.21> | 5.21 | language version selector | 없음 |
--compiler-memory-mib <MiB> | 8192 | self compiler worker memory budget (8192); overrides TOPAZ_COMPILER_MEMORY_MIB A positive integer is required. Environment input: TOPAZ_COMPILER_MEMORY_MIB. | 없음 |
--compiler-time-ms <ms> | 1800000 | self compilation wall-clock budget (1800000); overrides TOPAZ_COMPILER_TIME_MS A positive integer is required. Environment input: TOPAZ_COMPILER_TIME_MS. | 없음 |
-- <args...> | 미지정 | run/build --run: explicit program args passed to exported main(args, stdin) ( | 없음 |
출력 채널
stdout
stderr
종료 상태
0
Checking and test execution finish successfully without deferred errors and explicit main returns Ok(0) when present.
1
Argument, package, checking, assertion, runtime, deferred-action, or process-result validation fails.
nonzero
An admitted explicit main returns Ok(code) with an integer from 1 through 255 and no deferred error changes the verdict.
효과
Read source, package metadata, lock data, and any declared replay input. Default SELF execution uses the native host. Runtime file operations follow that host's capabilities and can change admitted files. Those program effects remain after a failure. Compiler setup does not rewrite source, manifests, locks, or vendor content and may use owned temporary files.
Compiler setup and package loading perform no registry or network access. Runtime network behavior follows the executed program and its available operations. Declared extern replay supplies the configured external-call results.
Repeatability depends on the selected runtime host, source graph, dependencies, compiler, program arguments, standard input, environment, files, clocks, randomness, replay data, and external service responses. Equal source bytes alone do not determine a native test's output or exit status.
Package checks and required lock validation finish before the test starts. A selected entry uses its package's dependencies when the explicit root contains a manifest. Missing dependencies never trigger a fetch.
Registry dependencies or Lispex configuration require explicit -, even when a matching lock exists. Without that option, a local-only package can load declared path dependencies by their expected hashes. Locked loading rejects missing or stale state and never repairs it.
Standalone entry mode rejects -. Selected-entry test is the exception when an explicit root contains the package manifest and the entry belongs to that package.
Operation
링크Use test to check and execute the selected unit. The test execution contract defines completion and host effects.
Option conditions
링크--locked applies to package-mode check, run, emit, build, test, doc, bench, compiler observe, compiler preview. Selected-entry test also accepts it when --root contains topaz.toml.
- cannot be combined with bootstrap - or -
Behavior contract
링크Command behavior
Arguments and rejection
Accept zero or one entry operand, the listed compiler and package selectors, and program arguments after -. A selected entry with - naming a package must be an admitted file under that package root.
With no entry, test the package entry. Reject standalone -, unsupported JSON output, export inspection, profile selectors, and invalid program input signatures before execution.
Output
Program output uses standard output. Default SELF execution streams output through the native host. The test completion rule defines the success and failure footers.
Deferred-action errors use standard error and make the test fail. A test with a deferred-action error must not print test-, even when its main result is Ok(0). - is rejected and no JSON report is supplied.
Exit status
Exit 0 means checking and test execution succeeded with no deferred error and a zero process result. Argument, package, checking, assertion, runtime, deferred-action, and host failures exit 1.
An admitted explicit main returns Result<int, string>. Ok(code) with an integer from 1 through 255 is preserved as a failing process exit. Err(message) writes the string to standard error and exits 1. Out-of-range codes and invalid result shapes fail with exit 1.
Filesystem effects
Read source, package metadata, lock data, and any declared replay input. Default SELF execution uses the native host. Runtime file operations follow that host's capabilities and can change admitted files. Those program effects remain after a failure. Compiler setup does not rewrite source, manifests, locks, or vendor content and may use owned temporary files.
Network access
Compiler setup and package loading perform no registry or network access. Runtime network behavior follows the executed program and its available operations. Declared extern replay supplies the configured external-call results.
Reproducibility
Repeatability depends on the selected runtime host, source graph, dependencies, compiler, program arguments, standard input, environment, files, clocks, randomness, replay data, and external service responses. Equal source bytes alone do not determine a native test's output or exit status.
Packages and locks
Package checks and required lock validation finish before the test starts. A selected entry uses its package's dependencies when the explicit root contains a manifest. Missing dependencies never trigger a fetch.
Registry dependencies or Lispex configuration require explicit -, even when a matching lock exists. Without that option, a local-only package can load declared path dependencies by their expected hashes. Locked loading rejects missing or stale state and never repairs it.
Standalone entry mode rejects -. Selected-entry test is the exception when an explicit root contains the package manifest and the entry belongs to that package.
이유
A test result must include checking, runtime assertions, and deferred cleanup. Separating diagnostics from successful output prevents an early success message from hiding a later failure.
The linked public CLI recipe checks the exact displayed argument rejection before the requested operation. It does not execute the successful operation or verify its effects.
The safe recipe checks rejection of JSON output. Native test execution, deferred failures, explicit process results, and selected package entries require other argument vectors. The deferred-error case requires a program whose cleanup fails after main returns Ok(0) and must assert exit 1 and absence of test-. That case is not executed by this recipe runner.
Example contract
링크Example contract
The invocation topaz test main. is expected to exit with 1.
This command does not provide a JSON report format. The invocation is rejected during argument validation before processing the program.
이유
This command does not provide a JSON report format. Rejecting the option prevents a successful exit from silently ignoring the requested output format.
Example
링크Argument-rejection example
링크function identity<T>(value: T) -> T {value}
기대 결과
기대 결과
Textual rejection details remain Pending in the reference model. The independent Tools example gate expects exit 1.
This command does not provide a JSON report format. The invocation is rejected during argument validation before processing the program.
Verification scope
링크Observed with Topaz 5.21.3 on 2026-11-06T08:36:29.642Z. This invocation passed; exit 1. 3 assertions were evaluated against the independent expected result. Execution record. This result covers the displayed invocation.