mops bench

Run Motoko benchmarks.

mops bench [filter]

Put your benchmark code in bench/*.bench.mo files.

It is necessary to use bench package to write benchmarks.

The output format is a markdown table, so you can copy-paste it into your README.md.

How it works

Under the hood, Mops will:

• Start a local replica on port 4944
• Wrap each *.bench.mo file in a canister
• Compile canisters with --force-gc flag and deploy them
• Run each cell of the benchmark file as an update call
• For each call measure usage of wasm instructions(performance_counter) and heap size(rts_heap_size)

Instruction counts depend on the replica

The number you get is for the exact wasm the chosen replica runs, and the two replicas install it differently:

• pocket-ic runs the raw moc output — no optimization.
• dfx post-optimizes the module before installing it (optimize: "cycles", via ic-wasm), so its instruction counts can be meaningfully lower.

The same benchmark can therefore report different numbers across replicas. Always compare runs made with the same replica.

Also note that dfx's optimization is best-effort: if it fails (for example, on wasm modules using features the bundled ic-wasm can't process, such as multi-value), dfx prints WARNING: Failed to optimize the Wasm module and falls back to the unoptimized module. Run with --verbose to see this warning.

Options

--replica

Which replica to use.

Default pocket-ic if pocket-ic is specified in mops.toml in [toolchain] section, otherwise dfx (deprecated, see below).

Possible values:

• pocket-ic - use PocketIC light replica via pic.js. Recommended.
• dfx - deprecated. Uses dfx local replica. Will be removed in a future release. Run mops toolchain use pocket-ic 12.0.0 to pin a PocketIC version and mops bench will use it directly.

--gc

Select garbage collector.

Possible values:

• copying (default)
• compacting
• generational
• incremental

--save

Save benchmark results to .bench/<filename>.json file.

--compare

Compare benchmark results with the results from .bench/<filename>.json file.

--verbose

Print the benchmark pipeline up front — compiler version, replica + version, GC, profile, and whether the wasm is optimized — then log the full moc build command and stream the compiler and dfx output (including any deploy/optimization warnings) instead of hiding it.