Docs
Testing

Test configuration

Learn how to configure test runner behavior through project settings and command line options

Default test behavior is set in Acton.toml. Command-line flags override those defaults for a single run.

Configuration methods

Acton supports two methods for configuring test behavior:

  • Project configuration: set defaults in Acton.toml.
  • Command-line flags: override defaults for a specific run.

Configuration precedence

When both methods are used, the precedence order is:

  1. Command line flags (highest priority) — override matching project settings.
  2. Acton.toml settings (medium priority) — project defaults.
  3. Built-in defaults (lowest priority) — fallback values.

Project configuration in Acton.toml

Basic configuration

Add a [test] section to Acton.toml to set default test behavior:

Acton.toml
[package]
name = "my-ton-project"
version = "0.1.0"

[test]
# Enable detailed backtraces
backtrace = "full"

[test.fuzz]
# Use 512 accepted inputs for fuzz tests marked with @test.fuzz
runs = 512
# Fix the seed for reproducible fuzz runs
seed = 42

[test.coverage]
# Enable code coverage by default
enabled = true
format = "lcov"
minimum-percent = 80

Command-line overrides

Many configuration options can be overridden with command-line flags:

# Use specific reporter
acton test --reporter console

# Compact progress reporter
acton test --reporter dot

# Use multiple reporters
acton test --reporter console,junit

# TeamCity with console output
acton test --reporter console,teamcity

# Override coverage setting from config
acton test --coverage

# Override filter setting from config
acton test --filter "mint.*"

# Override reporter setting
acton test --reporter teamcity

# Multiple overrides
acton test --coverage --filter "test deploy" --debug --reporter junit

Configuration options reference

Filter options

ConfigurationCLI FlagTypeDescription
filter--filterStringRegex pattern to filter test names
exclude--excludeArrayGlob patterns to exclude test files
include--includeArrayGlob patterns to include only test files

Examples:

Acton.toml
[test]
filter = ".*wallet.*"              # Only tests whose names have "wallet" within
exclude = ["**/integration/**"]    # Skip integration directory
include = ["**/unit/**"]           # Only include unit test files

Execution options

ConfigurationCLI FlagTypeDescription
fail-fast--fail-fastBooleanStop executing tests after the first failure

Examples:

Acton.toml
[test]
fail-fast = true

Reporter options

ConfigurationCLI FlagTypeDescription
reporter--reporterArrayTest output format(s)

Supported reporters:

  • console — Detailed console output with code context (default)
  • teamcity — TeamCity CI integration (minimal output, best combined with console)
  • junit — JUnit XML reports for external tools
  • dot — Compact dot-style progress with detailed failure diagnostics at the end

TeamCity integration

For TeamCity CI, combine the teamcity and console reporters so detailed test output appears alongside CI integration data.

acton test --reporter console,teamcity

Examples:

Acton.toml
[test]
# Use multiple reporters
reporter = ["console", "junit"]

# Single reporter
reporter = ["teamcity"]

# Compact progress reporter
reporter = ["dot"]

# For TeamCity CI, combine with console for detailed output
reporter = ["console", "teamcity"]

Debug options

ConfigurationCLI FlagTypeDescription
debug--debugBooleanEnable debug mode
debug-port--debug-portIntegerDebug server port
backtrace--backtraceStringEnable stack traces ("full")
---verboseCountEnable level-1 executor debug logs (CLI only)

--verbose is currently binary in practice: default level 0, and level 1 when --verbose is passed once. Higher user-selected levels are not supported yet.

Examples:

Acton.toml
[test]
debug = false
debug-port = 12345
backtrace = "full"
acton test --verbose --filter "debug.*"

Coverage options

ConfigurationCLI FlagTypeDescription
[test.coverage].enabled--coverageBooleanEnable code coverage
[test.coverage].format--coverage-formatStringCoverage output format (lcov, text)
[test.coverage].output-file--coverage-fileStringPath to save the coverage report
[test.coverage].minimum-percent--coverage-minimum-percentNumberFail when the blended coverage score is below this percentage
[test.coverage].include-wrappers--coverage-include-wrappersBooleanInclude files from the @wrappers mapping in coverage reports
[test.coverage].include-tests--coverage-include-testsBooleanInclude .test.tolk files in coverage reports

Examples:

Acton.toml
[test.coverage]
enabled = true
format = "lcov"
minimum-percent = 80
include-wrappers = true
include-tests = true

--coverage-minimum-percent is ignored when the run also starts Test UI with --ui.

Fuzz options

These defaults apply only to parameterized tests that explicitly opt in with @test.fuzz, @test.fuzz(<runs>), or @test.fuzz({ ... }). Per-test annotations can override them with @test.fuzz({ runs: ..., max_test_rejects: ..., seed: ... }). When max-test-rejects is omitted, Acton uses runs * 256.

See the fuzz testing guide for annotation syntax, helper APIs, supported parameter types, and failure reporting.

ConfigurationCLI FlagTypeDescription
[test.fuzz].runs-IntegerNumber of accepted fuzz cases to execute for each fuzz test
[test.fuzz].max-test-rejects-IntegerMaximum assume(...) rejections before the fuzz test fails
[test.fuzz].seed--fuzz-seedIntegerSeed for reproducible fuzz input generation

Examples:

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

Profiling options

ConfigurationCLI FlagTypeDescription
fail-on-diff--fail-on-diffBooleanExit with non-zero code when profiling differs from baseline snapshot
gas-profile--gas-profileStringPath to write a gas-weighted execution profile
gas-profile-format--gas-profile-formatStringGas profile output format (cpuprofile, collapsed)
gas-profile-include-tests--gas-profile-include-testsBooleanInclude .test.tolk unit-test get-method execution in the profile

fail-on-diff is applied when running baseline comparison mode with --baseline-snapshot <FILE>. Gas profile options apply when gas-profile or --gas-profile <FILE> is set. Combine --gas-profile <FILE> with --ui to browse the profile as a flamegraph in Test UI. Add --gas-profile-include-tests when the expensive work is executed directly from .test.tolk unit-test get methods.

Examples:

Acton.toml
[test]
fail-on-diff = true
gas-profile = "build/gas.cpuprofile"
gas-profile-format = "cpuprofile"
gas-profile-include-tests = false
acton test --baseline-snapshot gas-baseline.json --fail-on-diff
acton test --gas-profile build/gas.collapsed --gas-profile-format collapsed
acton test --gas-profile build/gas.cpuprofile --gas-profile-include-tests --ui

Mutation testing options

These defaults apply when the run is started with acton test --mutate --mutate-contract <NAME>.

ConfigurationCLI FlagTypeDescription
[test.mutation].diff--mutation-diffStringLimit mutation testing to changed lines in worktree, ref, or branch scope
[test.mutation].diff-ref--mutation-diff-refStringBase ref used by ref mode and optional override for branch mode
[test.mutation].mutation-levels--mutation-levelsArrayRun only selected levels such as critical, major, or minor
[test.mutation].rules-file--mutation-rules-fileStringPath to a JSON file with custom query-based mutation rules
[test.mutation].minimum-percent--mutation-minimum-percentNumberFail when the mutation score is below this percentage
[test.mutation].disable-rules--mutation-disable-rulesArrayDisable selected built-in or custom mutation rules

Examples:

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

JUnit options

ConfigurationCLI FlagTypeDescription
junit-path--junit-pathStringJUnit XML output directory
junit-merge--junit-mergeBooleanMerge all suites into one file

Examples:

Acton.toml
[test]
# Custom JUnit output directory
junit-path = "custom-reports"
junit-merge = true

Test UI options

ConfigurationCLI FlagTypeDescription
ui--uiBooleanStart the browser Test UI after the run
ui-port--ui-portIntegerUI server port, defaulting to 12344

Examples:

Acton.toml
[test]
ui = true
ui-port = 23456

Fork testing options

ConfigurationCLI FlagTypeDescription
fork-net--fork-netstringNetwork name to fork state from (mainnet, testnet, or custom:<name> for a custom network defined in [networks]).
fork-block-number--fork-block-numberintegerSpecific block number to fork from.

Examples:

Acton.toml
[test]
fork-net = "mainnet"

Use TONCENTER_TESTNET_API_KEY or TONCENTER_MAINNET_API_KEY to supply fork targets with higher RPS limits.

Using a custom network:

Acton.toml
[networks.archive-rpc]
api = { v2 = "https://your-rpc.example/api/v2/jsonRPC" }

[test]
fork-net = "custom:archive-rpc"

Last updated on

Fuzz testing

Run parameterized tests with generated inputs, assumptions, and bounds

World state snapshots

Save and restore test runner world state as JSON fixtures with testing.saveSnapshot() and testing.loadSnapshot()

On this page

Configuration methods
Configuration precedence
Project configuration in Acton.toml
Basic configuration
Command-line overrides
Configuration options reference
Filter options
Execution options
Reporter options
Debug options
Coverage options
Fuzz options
Profiling options
Mutation testing options
JUnit options
Test UI options
Fork testing options