Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ton-blockchain/acton/llms.txt

Use this file to discover all available pages before exploring further.

acton test discovers and executes tests from .test.tolk files. It is the most fully-featured Acton command: it supports per-test filtering, multiple report formats, code-coverage collection, gas-usage snapshots, mutation testing, transaction-trace export, remote-state forking, and a browser UI for exploring results interactively. Tests are run locally in the TVM emulator — no live network connection is required unless --fork-net is used.

​
Synopsis

acton test [OPTIONS] [PATH]
PATH can be a single .test.tolk file or a directory. When omitted, Acton discovers tests recursively from the project root.

​
Filtering

FlagTypeDefaultDescription
-f, --filter <PATTERN>regex—Run only tests whose name matches the regular expression.
--exclude <GLOB>glob—Exclude test files and directories matching the glob. Repeatable.
--include <GLOB>glob—Include only test files and directories matching the glob. Repeatable.

​
Execution

FlagTypeDefaultDescription
--fail-fast[=<BOOL>]bool[test].fail-fast or falseStop after the first failing test.
--fuzz-seed <SEED>u64—Seed for reproducible fuzz runs. Overrides [test.fuzz].seed.
--verbosecount0Increase executor log verbosity (level 1 only). Useful for debug.dumpStack() output.

​
Debugging

FlagTypeDefaultDescription
--debugflagfalseEnable debug mode. Raises verbosity and collects source locations for live stepping.
--debug-port <PORT>u1612345Port for the debug server.
--backtrace <LEVEL>full—Enable execution backtraces. full collects source locations and call stacks without opening the debugger.

​
Coverage

FlagTypeDefaultDescription
--coverageflagfalseGenerate a code-coverage profile.
--coverage-format <FORMAT>lcov | text—Output format for the coverage report.
--coverage-file <PATH>pathlcov.info / coverage.txtOutput file for the coverage report.
--coverage-minimum-percent <PERCENT>f64 (0–100)—Fail if the final blended coverage score is below this percentage. Ignored when --ui is enabled.
--coverage-include-wrappersflagfalseInclude files from the @wrappers mapping in coverage reports.
--coverage-include-testsflagfalseInclude .test.tolk files and tests/ directories in coverage reports.
Coverage excludes wrapper and test sources by default. Use --coverage-include-wrappers and --coverage-include-tests to opt in. The --coverage-minimum-percent threshold checks the blended Score column in the summary, not just % Lines.

​
Profiling (gas snapshots)

FlagTypeDefaultDescription
--snapshot <PATH>path—Write gas usage statistics to a JSON snapshot file.
--baseline-snapshot <PATH>path—Compare current gas usage against a baseline snapshot.
--fail-on-diffflagfalseExit non-zero when profiling differs from the baseline. Requires --baseline-snapshot.
When both --snapshot and --baseline-snapshot are provided, Acton runs in comparison mode and does not overwrite the snapshot file.

​
Reporting

FlagTypeDefaultDescription
--reporter <FORMAT>[,<FORMAT>...]console | teamcity | junit | dot—Report format(s). Overrides [test].reporter. Comma-separated or repeated.
--show-bodiesflagfalseShow decoded message bodies in transaction trees when ABI is known.
--junit-path <PATH>path[test].junit-path or test-resultsOutput directory for JUnit XML reports (used when the junit reporter is active).
--junit-mergeflagfalseMerge all test suites into a single JUnit XML file.
--uiflagfalseOpen test results in a browser UI.
--ui-port <PORT>u16[test].ui-port or 12344Port for the browser UI server.

​
Dot reporter

The dot reporter prints one character per test for compact progress and shows full failure diagnostics at the end of the run:
CharacterMeaning
·passed
xfailed
○skipped
□todo

​
Cache

FlagTypeDefaultDescription
--clear-cache[=<BOOL>]boolfalseClear the compilation cache before running.

​
Remote (fork mode)

FlagTypeDefaultDescription
--fork-net <NETWORK>string—Fork blockchain state from mainnet, testnet, or custom:<name> for remote account resolution. Execution remains local.
--fork-block-number <SEQNO>u64—Historical block sequence number to fork from.
Built-in networks read TONCENTER_MAINNET_API_KEY or TONCENTER_TESTNET_API_KEY. Custom networks (custom:<name>) read <NORMALIZED_NAME>_API_KEY. Keep keys in .env — Acton loads it automatically.

​
Tracing

FlagTypeDefaultDescription
--save-test-trace [DIR]pathbuild/tracesSave transaction traces to a directory. Each test produces <test-name>_trace.json. Contract metadata is written to contracts/<contract-name>.json.
--ui automatically enables build/traces when --save-test-trace is not set explicitly.

​
Mutation testing

FlagTypeDefaultDescription
--mutateflagfalseEnable mutation testing mode.
--mutate-contract <CONTRACT_NAME>string—Contract to mutate.
--mutation-rules-file <PATH>path—JSON file with custom query-based mutation rules. Custom rules are merged with built-in rules; same ID overrides.
--mutation-session-id <ID>string—Session ID for progress logging to build/mutation-sessions/<ID>.jsonl and resume.
--mutation-workers <N>usize (≥1)available parallelismNumber of parallel mutation workers.
--mutation-diff <MODE>worktree | ref | branch—Limit mutations to lines changed in the selected diff scope.
--mutation-diff-ref <REF>string—Base ref for diff-based mutation modes. Required with ref; optional with branch.
--mutation-levels <LEVEL[,LEVEL...]>critical | major | minor—Run only selected mutation levels. Comma-separated or repeated.
--mutation-id <ID>usize (≥1)—Re-run specific mutation IDs from a previous report. Comma-separated or repeated.
--mutation-minimum-percent <PERCENT>f64 (0–100)—Fail if the mutation score is below this percentage.
--mutation-disable-rules <RULE>string—Disable a specific mutation rule. Repeatable.

​
Mutation session resume

When you press Ctrl+C during a mutation run, Acton prints a resume command that includes the same --mutation-session-id. Re-run with the same filters and session ID to continue from where the run stopped.

​
Acton.toml configuration

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

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

[test.coverage]
enabled             = true
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 [test] values for the current invocation.

​
Examples

acton test

Build docs developers (and LLMs) love

Get started for freeTalk to us