acton test

Synopsis

acton test [options] [path]

Description

Discover and execute tests from .test.tolk files.

The test runner supports filtering, multiple reporters, coverage collection, gas snapshots, mutation testing, trace export, remote-state fork mode, and a browser UI for exploring results.

Options

Discovery Options

Execution Options

Debugging Options

Coverage Options

Profiling Options

Reporting Options

Cache Options

Remote Options

Tracing Options

TonCenter API Keys

When tests fork from the built-in mainnet/testnet backends, authenticated requests read TONCENTER_MAINNET_API_KEY or TONCENTER_TESTNET_API_KEY.

When tests fork from custom:<name>, Acton reads <NORMALIZED_NAME>_API_KEY. Custom network names are uppercased and non-alphanumeric characters are replaced with _, so custom:mock-remote becomes MOCK_REMOTE_API_KEY.

Acton loads .env automatically, so the simplest setup during project work is usually to keep these keys there and use shell environment variables only for one-off overrides or CI.

Mutation Testing Options

Display Options

Project Options

Discovery

Acton discovers tests by finding files that end with .test.tolk.

• If _path_ is omitted, discovery starts at the resolved project root
• If _path_ is a directory, search is recursive
• Relative _path_ values are resolved from the current working directory

Reporting And Artifacts

• --reporter on the CLI overrides [test].reporter for the current run
• --ui adds the browser UI in addition to text reporters
• --coverage --ui adds a Coverage tab to the browser UI for browsing coverage summaries, files, and annotated source
• --junit-path matters when the JUnit reporter is enabled; it defaults to [test].junit-path, or test-results when it is not configured
• executor debug logs are hidden by default; re-run with --verbose when you need level-1 executor output such as debug.dumpStack()
• --verbose is only low-level executor logging; --coverage also collects source-location data, while --backtrace full and --debug collect richer location and stack data
• --coverage-file matters only with --coverage; without an explicit path, Acton writes lcov.info for lcov and coverage.txt for text
• coverage summaries show line and branch columns plus a blended Score
• LCOV export includes BRDA, BRF, and BRH records when branch sites were observed for a file
• --coverage-minimum-percent checks the final blended Score shown in the summary, not just % Lines
• coverage excludes files under tests/, .test.tolk files, and @wrappers sources by default; use --coverage-include-tests or --coverage-include-wrappers to opt in
• --save-test-trace without a value writes traces to build/traces
• each executed test produces its own <test-name>_trace.json artifact
• exported bundles also include contracts/<contract-name>.json files with code, source maps, and ABI metadata reused across tests in the same bundle
• trace chains default to names like Trace 1; use txs.giveName("...") when you want stable human-readable names in exported artifacts and the Test UI
• when you split execution with testing.createTraceIterationCursor(), exported traces still merge batches that belong to the same logical root transaction chain
• --ui also enables the default trace bundle directory when --save-test-trace is otherwise absent
• gas snapshot files are written only to the explicit paths passed to --snapshot or --baseline-snapshot
• [test.fuzz] applies only to parameterized tests that explicitly opt in with @test.fuzz, @test.fuzz(<runs>), or @test.fuzz({ ... })
• --fuzz-seed overrides [test.fuzz].seed for the current run
• fuzz tests show the seed in console output; if [test.fuzz].seed is omitted, Acton picks a new seed for each acton test run

Dot Reporter

Use dot when you want compact progress output but still need full failure diagnostics at the end of the run:

acton test --reporter dot

The progress line uses one character per test:

• · passed
• x failed
• ○ skipped
• □ todo

When a test fails, the dot reporter prints the same important diagnostics as the console reporter after the progress line: assertion diffs, transaction trees, get-method errors, fuzz seed and input values, stdout/stderr, and source locations. With --backtrace full, runtime failures also include backtrace frames:

acton test --reporter dot --backtrace full

If coverage is enabled, dot failure details are printed before the coverage summary so the failing test remains visible near the progress output.

Configuration

Defaults can be configured in Acton.toml:

[test]
reporter = ["console"]
filter = ".*jetton.*"
junit-path = "reports"
junit-merge = false

[test.fuzz]
runs = 512
max-test-rejects = 4096
seed = 42

[test.coverage]
enabled = true
# valid range: 0..=100
minimum-percent = 85
include-tests = true
include-wrappers = true

[test.mutation]
diff = "branch"
diff-ref = "origin/main"
mutation-levels = ["critical", "major"]
minimum-percent = 85
disable-rules = ["replace_plus_with_minus"]

CLI flags override config values for the current invocation.

Notes

• If both --snapshot and --baseline-snapshot are provided, Acton runs in comparison mode and does not overwrite the snapshot file
• --fail-on-diff requires --baseline-snapshot
• The UI and trace export features are useful for debugging failing tests and inspecting transaction trees
• You can combine --coverage and --ui to inspect the current run's coverage directly in the browser UI
• --coverage-minimum-percent and [test.coverage].minimum-percent are ignored when --ui is enabled
• --fork-net keeps execution local while resolving blockchain state remotely
• --mutation-diff worktree is intended for uncommitted local changes
• --mutation-diff ref requires --mutation-diff-ref
• --mutation-diff branch uses the upstream branch merge-base by default
• --mutation-rules-file loads custom query-based rules from JSON and custom rules override built-in rules with the same ID
• --mutation-session-id writes append-only JSONL progress to build/mutation-sessions/<ID>.jsonl
• --mutation-workers defaults to the host's available parallelism; each worker reuses its own isolated mutation workspace
• pressing Ctrl+C during mutation testing stops the run without finalizing the session and prints a resume command for the same session ID
• --mutation-id expects mutation numbers from a previous run with the same mutation filters and session selection
• mutation scores in filtered runs only cover the selected mutants
• --mutation-minimum-percent and [test.mutation].minimum-percent apply to that filtered mutation score after compile errors are excluded

Exit Status

• 0: All selected tests passed, or a non-mutating reporting mode completed successfully.
• 1: At least one test failed, profiling drift was detected with --fail-on-diff, line coverage was below the configured minimum in non-UI coverage mode, mutation score was below the configured minimum in mutation mode, no tests matched after filtering, or infrastructure such as compilation, trace export, UI startup, or remote-state resolution failed.

Examples

1. Run all tests:

   acton test

2. Filter tests by name:

   acton test --filter "wallet.*"

3. Show executor debug logs from debug.* helpers:

   acton test --verbose --filter "debug.*"

4. Generate coverage and JUnit output:

   acton test --coverage --coverage-format lcov --reporter junit --junit-path test-results

5. Fail the run when line coverage drops below 85%:

   acton test --coverage --coverage-minimum-percent 85

6. Compare gas usage against a baseline:

   acton test --baseline-snapshot build/gas-baseline.json --fail-on-diff

7. Run mutation testing for one contract:

   acton test --mutate --mutate-contract Wallet

8. Run mutation testing only for changed lines in the current worktree:

   acton test --mutate --mutate-contract Wallet --mutation-diff worktree

9. Run mutation testing for selected levels on the current branch:

   acton test --mutate --mutate-contract Wallet --mutation-diff branch --mutation-levels critical,major

10. Re-run one specific mutant from a previous report:

acton test --mutate --mutate-contract Wallet --mutation-id 2

11. Resume an unfinished mutation session:

acton test --mutate --mutate-contract Wallet --mutation-session-id wallet-pr-42 --mutation-diff worktree

12. Fail the run when mutation score drops below 85%:

acton test --mutate --mutate-contract Wallet --mutation-minimum-percent 85

13. Limit mutation testing to four workers:

acton test --mutate --mutate-contract Wallet --mutation-workers 4

14. Debug a forked-state failure with traces and the UI:

acton test tests/wallet.test.tolk --fork-net testnet --fork-block-number 55000000 --save-test-trace --ui

15. Enforce a gas baseline in CI:

acton test --baseline-snapshot build/gas-baseline.json --fail-on-diff --reporter console,junit

See Also

• acton help wrapper
• Test runner guide