DUNE-RUNTEST(1)

📦

version 3.24.1 · 15 versions

💅 DUNE-RUNTEST — run them tests, bestie

ok so this is the manual page for dune-runtest, aka the Dune command that runs your tests. It's giving ✨ build-system-girlie ✨ energy and honestly? iconic.

🌸 NAME

dune-runtest — run tests. that's it. that's the whole vibe. 🧚

✨ SYNOPSIS

dune runtest [OPTION]… [TEST]…

🦋 DESCRIPTION

So you wanna run some tests? Say less. 💖

You pass it a [TEST] argument, and that argument can be one of two things:

A directory 📁 — if you hand it a directory, dune will recursively run all the tests chilling inside that directory. every last one. it goes and finds them.
A file name 📄 — if you give it a specific file name, dune runs the tests with that name. just that one.

And if you don't pass a [TEST] at all? No worries, bestie — dune just runs all the tests in the current directory and all its subdirectories. go big or go home. 💅

peek the EXAMPLES section further down for more inspo on how to use this 👀

🎀 OPTIONS

--action-stderr-on-success=VAL — literally the same as --action-stdout-on-success except for standard error instead of standard output. and ngl, for big old mono-repos the slay combo is --action-stdout-on-success=swallow plus --action-stderr-on-success=must-be-empty. that way a successful build has a "clean", empty output. chef's kiss. 🧑‍🍳💋
--action-stdout-on-success=VAL — tells dune how to handle an action's standard output when the action succeeds. the possible values are: print to just print it right to Dune's output, swallow to completely ignore it, and must-be-empty to enforce that the action printed nothing at all. with must-be-empty, if the action printed something to standard output, Dune counts that action as failed. the default is print.
--build-info — show build information. simple. 📋
--display-separate-messages — separates error messages with a blank line, so they don't all pile up on each other. visual breathing room. 🫶
--error-reporting=VAL (absent=deterministic) — controls when build errors get reported. early = errors get reported the second they're discovered. deterministic = errors get reported at the end of the build, in a deterministic order. twice = each error gets reported twice: once when it's discovered, and then again at the end of the build in deterministic order. drama queen behavior, we love it. 💅
-f, --force — forces the actions tied to aliases to be re-executed even if their dependencies haven't changed. like "no babe, run it again anyway." 🔥
--file-watcher=VAL (absent=automatic) — the mechanism used to detect changes in the source. automatic makes dune run an external program to detect changes. manual means you notify dune that files have changed, by hand. 👀
--passive-watch-mode — like --watch, but it only starts a build when it's instructed externally by an RPC. it's waiting for permission, honestly same. 🙈
--sandbox=VAL (absent DUNE_SANDBOX env) — sets the sandboxing mode. heads up: some actions require a certain sandboxing mode, so they'll straight up ignore this setting. the allowed values are: none, symlink, copy, hardlink.
--stop-on-first-error — stops the build the moment an error is encountered. no more, we're done here. ✋
-w, --watch — instead of terminating the build after completion, it just... keeps waiting, continuously, for file changes. forever girlie. 🔁
--wait-for-filesystem-clock — Dune digests file contents for better incrementality, and those digests are themselves cached. sometimes Dune needs to drop some digest cache entries for things to stay reliable. this option makes Dune wait for the file system clock to advance so it doesn't have to drop anything. you probably don't need to care about this one — it's mostly for Dune devs to make Dune's tests of the digest cache more reproducible. iykyk. 🧪

🌈 COMMON OPTIONS

these ones are common to all commands, so they're basically the whole squad. 🫶

--always-show-command-line — always show the full command lines of the programs dune executes. no secrets here. 👑
--auto-promote — automatically promotes files. this is similar to running dune promote after the build.
--build-dir=FILE (absent DUNE_BUILD_DIR env) — the specified build directory. _build if unspecified.
--cache=VAL (absent DUNE_CACHE env) — enable or disable the Dune cache. it's one of disabled, enabled-except-user-rules or enabled. default is enabled-except-user-rules.
--cache-check-probability=VAL (absent DUNE_CACHE_CHECK_PROBABILITY env) — checks build reproducibility by re-executing randomly chosen rules and comparing their results with the ones stored in Dune cache. ⚠️ note: by increasing the probability of these checks you slow down the build. the default probability is zero, i.e. no rules are checked.
--cache-storage-mode=VAL (absent DUNE_CACHE_STORAGE_MODE env) — Dune cache storage mode, one of auto, hardlink or copy. default is hardlink.
--config-file=FILE — loads this configuration file instead of the default one. ✨
--debug-backtraces — always print exception backtraces. for when you need the receipts. 🧾
--debug-dependency-path — in case of error, prints the dependency path from the targets on the command line all the way to the rule that failed. breadcrumb trail of sadness. 😭
--debug-package-logs (absent DUNE_DEBUG_PACKAGE_LOGS env) — always print the standard logs when building packages.
--default-target=TARGET (absent=@@default) — sets the default target used when none is specified to dune build.
--diff-command=VAL (absent DUNE_DIFF_COMMAND env) — the shell command used to diff files. use - to disable printing the diff.
--disable-promotion (absent DUNE_DISABLE_PROMOTION env) — disables all promotion rules. 🚫
--display=MODE — controls the display mode of Dune. see dune-config(5) for more details. the valid values for this option are progress, verbose, short, quiet or tui.
--dump-gc-stats=FILE — dumps the garbage collector stats to a file after the build is complete. 🗑️📊
--help[=FMT] (default=auto) — shows this help in format FMT. FMT has to be one of auto, pager, groff or plain. with auto, the format is pager or plain whenever the TERM env var is dumb or undefined.
--ignore-promoted-rules — ignores rules with (mode promote), except the ones with (only ...). the variable %{ignoring_promoted_rules} in dune files reflects whether this option was passed or not.
--instrument-with=BACKENDS (absent DUNE_INSTRUMENT_WITH env) — enables instrumentation by BACKENDS. BACKENDS is a comma-separated list of library names, and every one of them must declare an instrumentation backend.
-j JOBS (absent DUNE_JOBS env) — runs no more than JOBS commands simultaneously. JOBS must be a positive integer, or auto to auto-detect the number of cores (that's the default).
--no-buffer — do not buffer the output of commands executed by dune. by default dune buffers subcommand output to prevent interleaving when multiple commands run in parallel — but that can be a whole issue when you're debugging long running tests. with --no-buffer, commands get direct access to the terminal. ⚠️ note that as a result their output won't be captured in the log file. you should use this option together with -j 1 to avoid interleaving, and you should also use --verbose so that commands are printed before they're actually executed.
--no-config — do not load the configuration file.
--no-print-directory — suppresses "Entering directory" messages. we know what dir we're in bestie.
--only-packages=PACKAGES — ignores stanzas referring to a package that is not in PACKAGES. PACKAGES is a comma-separated list of package names. note that this has the same effect as deleting the relevant stanzas from dune files. it's mostly meant for releases. during development, what you probably want instead is to build a particular <package>.install target.
-p PACKAGES, --for-release-of-packages=PACKAGES (required) — shorthand for --release --pkg=disabled --only-packages PACKAGE. you must use this option in your <package>.opam files, so that you build only what's necessary when your project contains multiple packages, and so that you get reproducible builds.
--pkg=VAL — enable or disable package management. the default behaviour depends on whether a lock directory exists.
--profile=VAL (absent DUNE_PROFILE env) — selects the build profile, for instance dev or release. the default is dev.
--promote-install-files[=VAL] (default=true) — promotes any generated <package>.install files to the source tree.
--release — puts dune into a reproducible release mode. it's shorthand for:

--root . --ignore-promoted-rules --no-config --profile release --always-show-command-line --promote-install-files --require-dune-project-file --default-target @install

you should use this option for release builds. for instance, you must use it in your <package>.opam files. except if you already use -p, since -p implies this option.

--require-dune-project-file[=VAL] (default=true) — fails if a dune-project file is missing.
--root=DIR (absent DUNE_ROOT env) — uses this directory as the workspace root instead of guessing it. note that this option doesn't change the interpretation of targets given on the command line. it's only intended for scripts. 🤖
--store-orig-source-dir (absent DUNE_STORE_ORIG_SOURCE_DIR env) — stores the original source location in dune-package metadata.
--target-exec=TOOLCHAIN=CMD (absent DUNE_TARGET_EXEC env) — a wrapper command for running target binaries when cross-compiling. format: TOOLCHAIN=CMD (e.g., 'windows=wine').
--terminal-persistence=MODE — changes how the log of build results is displayed to the console between rebuilds while in --watch mode. supported modes: preserve, clear-on-rebuild, clear-on-rebuild-and-flush-history.
--trace-file=FILE — outputs trace data in catapult format (compatible with chrome://tracing). 📈
--verbose — same as --display verbose.
--version — shows version information.
--watch-exclusions=REGEX — adds a POSIX regular expression that excludes matching directories from dune build --watch. the option --watch-exclusions can be repeated to add multiple exclusions. semicolons can also be used as a separator. if no exclusions are provided, then a standard set of exclusions is used; however, if one or more --watch-exclusions are used, none of the standard exclusions are used. the standard exclusions are:

^_opam /_opam ^_esy /_esy ^\.#.* /\.#.* ~$ ^#[^#]*#$ /#[^#]*#$ ^4913$ /4913$ /.git /.hg :/windows

--workspace=FILE (absent DUNE_WORKSPACE env) — uses this specific workspace file instead of looking it up.
-x VAL (absent DUNE_CROSS_TARGET env) — cross-compiles using this toolchain. 🛠️

📖 MORE HELP

want help on just one command? run:

dune COMMAND --help

🚦 EXIT STATUS

dune runtest exits with:

0 — on success. 🎉
1 — if an error happened. 😭
130 — if it was interrupted by a signal. 💀

🌸 ENVIRONMENT 🌸

okay bestie, these env vars are the real main characters behind the scenes — they change how runtest behaves before you even lift a finger 💅

CLICOLOR — if it's anything other than 0, ANSI colors are supported and should be used whenever the program isn't being piped. If it equals 0, pls no ANSI color escape codes 🎀
CLICOLOR_FORCE — if it's different than 0, ANSI colors should be enabled no matter what. no vibe check, just color 🌈
DUNE_BUILD_DIR — the build directory you want. defaults to _build if you don't say anything ✨
DUNE_CACHE — turn Dune cache on or off. pick one of disabled, enabled-except-user-rules or enabled. default is enabled-except-user-rules 🦋
DUNE_CACHE_CHECK_PROBABILITY — check build reproducibility by re-executing randomly chosen rules and comparing their results with those stored in Dune cache. ⚠️ note: by increasing the probability of such checks you slow down the build. the default probability is zero, i.e. no rules are checked 😭
DUNE_CACHE_ROOT — if set, this determines the location of all the different caches used by dune 📁
DUNE_CACHE_STORAGE_MODE — Dune cache storage mode, one of auto, hardlink or copy. default is hardlink 💾
DUNE_CROSS_TARGET — cross-compile using this toolchain 🛠️
DUNE_DEBUG_PACKAGE_LOGS — always print the standard logs when building packages 📜
DUNE_DIFF_COMMAND — shell command to use to diff files. use - to disable printing the diff 🙈
DUNE_DISABLE_PROMOTION — disable all promotion rules 🚫
DUNE_INSTRUMENT_WITH — enable instrumentation by BACKENDS. BACKENDS is a comma-separated list of library names, and every single one of them must declare an instrumentation backend 🔬
DUNE_JOBS — run no more than JOBS commands simultaneously. JOBS must be a positive integer or auto to auto-detect the number of cores (that's the default, bestie) ⚡
DUNE_PROFILE — build profile. dev if unspecified, or release if -p is set 🎚️
DUNE_ROOT — use this directory as workspace root instead of guessing it. note that this option doesn't change the interpretation of targets given on the command line. it's only intended for scripts 👑 (it said the quiet part out loud)
DUNE_SANDBOX — sandboxing mode to use by default. (see --sandbox) 🏖️
DUNE_STORE_ORIG_SOURCE_DIR — store original source location in dune-package metadata 📦
DUNE_TARGET_EXEC — wrapper command for running target binaries when cross-compiling. Format: TOOLCHAIN=CMD (e.g., 'windows=wine') 🍷
DUNE_WORKSPACE — use this specific workspace file instead of looking it up 🔍

🐛 BUGS 🐛

found a bug? not the cute kind of bug. check bug reports at https://github.com/ocaml/dune/issues 💀

👀 SEE ALSO 👀

dune(1)

✨ EXAMPLES ✨

run all tests in a given directory:

dune runtest path/to/dir/

run a specific cram test:

dune runtest path/to/mytest.t

run all tests in the current source tree (including those that passed on the last run):

dune runtest --force

run tests sequentially without output buffering:

dune runtest --no-buffer -j 1

run tests in a specific build context:

dune runtest _build/my_context/

and that's the whole page, bestie 🫶 this was Dune 3.24.1 hitting you with DUNE-RUNTEST(1), and you absolutely ate it 💖 go forth and runtest, you iconic legend 💅✨

📦 where this page comes from

ubuntu stonking: ocaml-dune 3.24.1-4 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms