acton test

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

<path>...

Test files or directories to run.

If omitted:

Acton discovers tests from the resolved project root.

Repeatable:

May be passed multiple times.

-f,--filter<pattern>

Filter tests by regular expression.

--exclude<glob>

Exclude test files or directories matching a glob pattern.

Repeatable:

May be passed multiple times.

--include<glob>

Include only test files or directories matching a glob pattern.

Repeatable:

May be passed multiple times.

Execution Options

--fail-fast

Stop after the first failing test.

Default:

[test].fail-fast, or false when it is not configured.

Possible values:

true, false

--fuzz-seed<seed>

Seed for reproducible fuzz runs.

--verbose

Enable executor debug logs at verbosity level 1.

Currently only level 1 is supported. Pass --verbose at most once. Use this for low-level executor output such as debug.dumpStack(). For richer debug output, use --backtrace full or --debug.

Default:

0

Repeatable:

May be passed multiple times.

Debugging Options

--debug

Enable debug mode.

This also raises executor verbosity to collect full source locations and stack context for live stepping.

--debug-port<port>

Debug server port.

--backtrace<level>

Enable execution backtraces.

Currently supported value: full. Full backtraces also raise executor verbosity to collect source locations and call stacks without opening the debugger.

Possible values:

full

--no-capture

Print test println and eprintln output as it is produced.

The output is still captured for reporters such as JUnit and the test UI. Executor debug logs from --verbose, including debug.dumpStack(), are not printed live by this flag.

This flag is not supported with --mutate, because mutation testing executes child test processes and captures their output for mutation reports.

Conflicts with:

--mutate

Coverage Options

--coverage

Generate a coverage profile.

Coverage also raises internal executor verbosity enough to map executed locations back to source files and lines, but it does not enable stepping or print backtraces by itself.

--coverage-format<format>

Coverage output format.

Possible values:

lcov, text

--coverage-file<path>

Output file for the coverage report.

--coverage-minimum-percent<percent>

Fail when the final coverage score is below this percentage.

Valid range:

0 to 100.

Ignored with:

--ui.

--coverage-include-wrappers

Include files from the @wrappers mapping in coverage reports.

--coverage-include-tests

Include .test.tolk files in coverage reports.

Profiling Options

--snapshot<path>

Write gas usage statistics to a JSON snapshot file.

--baseline-snapshot<path>

Compare gas usage with a baseline snapshot.

--fail-on-diff

Exit non-zero when the current run differs from the baseline snapshot.

Requires:

--baseline-snapshot.

--gas-profile<path>

Write a gas-weighted execution profile.

By default, Acton records contract transactions produced by test messages. Combine with --ui to browse the profile as a flamegraph in the Test UI.

--gas-profile-format<format>

Execution profile output format.

Possible values:

cpuprofile, collapsed

--gas-profile-include-tests

Include .test.tolk unit-test get-method execution in the gas profile.

Use this when the expensive work is called directly from a unit test instead of through a contract message transaction.

Reporting Options

--reporter<format>[,<format>...]_

Report format list.

Possible values:

console, teamcity, junit, dot

Repeatable:

May be passed multiple times.

--show-bodies

Show decoded message bodies in printed transaction trees when ABI is known.

--junit-path<path>

Output directory for JUnit XML reports.

Default:

[test].junit-path, or test-results when it is not configured.

--junit-merge

Merge all test suites into a single JUnit XML file.

--ui

Open test results in a browser UI.

--ui-port<port>

Port for the browser UI server.

Default:

[test].ui-port, or 12344 when it is not configured.

Cache Options

--clear-cache

Clear the compilation cache before running tests.

Default:

false.

Possible values:

true, false

Remote Options

--fork-net<network>

Fork remote blockchain state for account resolution.

--fork-block-number<seqno>

Historical block sequence number to fork from.

When a fork block number is set, Acton caches resolved remote accounts under build/cache/<network>/<seqno>/<workchain>_<address-hash>.json. Later test runs with the same fork network, block number, and address read that file before calling the remote API.

--no-fork-cache

Disable persistent account cache for pinned fork block numbers. Use this when you want every test run to fetch forked accounts from the remote API. The regular --clear-cache flag removes this cache together with the rest of build/cache.

Tracing Options

--save-test-trace[<dir>]

Save transaction traces to a directory.

If passed without a value, Acton uses build/traces. Acton writes one <test-name>_trace.json file per executed test and stores shared contract metadata under contracts/<contract-name>.json. These filenames are derived only from the test name and contract name, so duplicate names overwrite earlier artifacts in the same output directory. Relative paths are resolved from the project root.

The Test UI also enables the default build/traces directory when trace export is not configured explicitly, including when UI is enabled through [test].ui.

Mutation Testing Options

--mutate

Run tests in mutation testing mode.

Conflicts with:

--no-capture

--mutate-contract<contract-name>

Contract name to mutate during mutation testing.

--mutation-diff<mode>

Limit mutation testing to changed lines in the selected diff scope.

Accepted values: worktree, ref, branch.

worktree compares the current worktree with HEAD and includes untracked files
ref compares against the explicit ref passed with --mutation-diff-ref
branch compares against the merge-base with the current branch upstream, or against --mutation-diff-ref when provided

Possible values:

worktree, ref, branch

--mutation-diff-ref<ref>

Base ref used by diff-based mutation testing modes.

Required with --mutation-diff ref. Optional with --mutation-diff branch. Use it with branch when the current branch has no upstream or when you want a different comparison base such as origin/main.

--mutation-levels<level[,level...]>

Run only selected mutation levels.

Accepted values: critical, major, minor. Useful for faster local runs such as critical,major.

Possible values:

critical, major, minor

Repeatable:

May be passed multiple times.

--mutation-rules-file<path>

Load custom query-based mutation rules from a JSON file.

Custom rules are merged with built-in rules. If a custom rule uses the same rule ID, it overrides the built-in one. Relative paths are resolved from the project root.

--mutation-session-id<id>

Use a specific mutation session ID for progress logging and resume.

Acton writes append-only JSON Lines progress to build/mutation-sessions/<ID>.jsonl. Re-run with the same session ID and the same mutation filters to continue an unfinished session. If you stop the run with Ctrl+C, Acton prints a resume command that includes the same session ID.

--mutation-workers<count>

Override the number of mutation workers.

By default, Acton uses the host's available parallelism. Each worker keeps its own isolated mutation workspace and reuses it across multiple mutants.

--mutation-id<id>

Run only specific mutation IDs from a previous mutation report.

Pass the mutation number shown in the report, and use the same mutation filters such as --mutation-diff, --mutation-levels, and --mutation-disable-rules as the original run. May be passed multiple times or as a comma-separated list.

Repeatable:

May be passed multiple times.

--mutation-minimum-percent<percent>

Fail if mutation score is below this percentage.

Valid range:

0..=100.

--mutation-disable-rules<rule>

Disable a specific mutation rule.

Repeatable:

May be passed multiple times.

Display Options

--color<when>

Control when to use colored output.

Possible values:

auto, always, never

Default:

auto

Project Options

--manifest-path<path>

Path to the Acton.toml file to use for this invocation.

Use this when running the command outside the project directory or when the manifest lives at a non-default location.

Conflicts with:

--project-root

--project-root<path>

Path to the project root to use for configuration discovery and relative defaults.

Conflicts with:

--manifest-path

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.

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
--gas-profile --ui adds a Profile tab to the browser UI; the top-level view is grouped by contract, and selected tests with recorded samples get a per-test profile next to Info, Transactions, and Logs
--junit-path matters when the JUnit reporter is enabled; it defaults to [test].junit-path, or test-results when it is not configured
--no-capture prints println and eprintln output during the test run, while keeping captured stdout and stderr available to non-console reporters
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
gas execution profiles are written only to the explicit path passed to --gas-profile; relative paths are resolved from the project root
--gas-profile-format cpuprofile writes Chrome DevTools-compatible JSON; --gas-profile-format collapsed writes folded stacks for flamegraph-style tooling
--gas-profile-include-tests records .test.tolk unit-test get-method execution; the Test UI hides Acton runtime frames from the per-test profile, but exported cpuprofile and collapsed files remain complete
[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:

Acton.toml

[test]
reporter = ["console"]
filter = ".*jetton.*"
junit-path = "reports"
junit-merge = false
gas-profile = "build/gas.cpuprofile"
gas-profile-format = "cpuprofile"
gas-profile-include-tests = 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
--gas-profile-format and --gas-profile-include-tests affect output only when --gas-profile or [test].gas-profile is configured
The UI and trace export features are useful for debugging failing tests and inspecting transaction trees
Test UI writes trace bundles to build/traces by default unless --save-test-trace or [test].save-test-trace chooses another directory
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

Run all tests:
```
acton test
```

Run selected test files/directories:

acton test tests/wallet.test.tolk tests/jetton

Filter tests by name:
```
acton test --filter "wallet.*"
```
Show executor debug logs from debug.* helpers:
```
acton test --verbose --filter "debug.*"
```

Generate coverage and JUnit output:

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

Fail the run when line coverage drops below 85%:

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

Compare gas usage against a baseline:

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

Write a collapsed gas execution profile:

acton test --gas-profile build/gas.collapsed --gas-profile-format collapsed

Open Test UI with gas profile flamegraphs:

acton test --gas-profile build/gas.cpuprofile --ui

Run mutation testing for one contract:

acton test --mutate --mutate-contract Wallet

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

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

Run mutation testing for selected levels on the current branch:

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

Re-run one specific mutant from a previous report:

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

Resume an unfinished mutation session:

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

Fail the run when mutation score drops below 85%:

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

Limit mutation testing to four workers:

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

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

Enforce a gas baseline in CI:

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

acton test

Synopsis

Description

Options

Discovery Options

Execution Options

Debugging Options

Coverage Options

Profiling Options

Reporting Options

Cache Options

Remote Options

Tracing Options

Mutation Testing Options

Display Options

Project Options

TonCenter API Keys

Discovery

Reporting And Artifacts

Dot Reporter

Configuration

Notes

Exit Status

Examples

See Also

On this page