DUNE-TEST(1)

📦
version 3.24.1 · 15 versions
, in ubuntu stonking

💖 dune-test — the manual, but make it make sense 💖

okay bestie, welcome to DUNE-TEST(1) from the Dune Manual. section 1, terminal-core, group-chat-certified. this is part 1 of 2 so don't you dare scroll expecting a goodbye at the bottom, we're just getting started 🫶

✨ NAME ✨

dune-test — it's literally just an alias for runtest. that's it. that's the whole name section. iconic of it honestly 💅

✨ SYNOPSIS ✨

dune test [OPTION]… [TEST]…

✨ DESCRIPTION ✨

so, dune test is an alias for dune runtest. same energy, different word. they're the same thing, no cap 🎀

want the real tea? run dune runtest --help and read all the details for yourself, because that's where the full story lives.

✨ OPTIONS ✨

okay here's the part where people usually zone out, but not you, you're built different. stay with me 💖

  • --action-stderr-on-success=VAL — same as --action-stdout-on-success but for standard error instead of standard output. and listen, for big mono-repos a truly great default 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 the standard output of actions when they succeed. the possible values are:
    • print — just print it to Dune's output.
    • swallow — completely ignore it.
    • must-be-empty — enforce that the action printed nothing. with this one, if the action printed anything at all to its stdout, Dune considers the action failed. 💀

the default is print.

  • --build-info — show build information. that's the whole vibe.
  • --display-separate-messages — puts a blank line between error messages so they don't all mush into one giant wall of doom.
  • --error-reporting=VAL (absent=deterministic) — controls when build errors get reported:
    • early — reports errors the second they're discovered.
    • deterministic — reports errors at the end of the build in a deterministic order.
    • twice — reports each error twice: once immediately when discovered, and then again at the end of the build, in a deterministic order. yes, twice. it's giving déjà vu 🙈
  • -f, --force — force actions tied to aliases to be re-executed even if their dependencies haven't changed. no skipping, we're doing the thing again 🔥
  • --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 — you notify Dune that files have changed, manually, yourself.
  • --passive-watch-mode — like --watch, but it only starts a build when instructed externally by an RPC. it's the chill, wait-to-be-asked version 😌
  • --sandbox=VAL (absent DUNE_SANDBOX env) — set the sandboxing mode. heads up: some actions require a certain sandboxing mode, so they'll just ignore this setting. allowed values are: none, symlink, copy, hardlink.
  • --stop-on-first-error — stop the build the moment an error shows up. no collecting them all, we're out ✋
  • -w, --watch — instead of terminating after the build completes, it just keeps waiting for file changes, forever, like a loyal little gremlin 👑
  • --wait-for-filesystem-clock — Dune digests file contents to be better at incremental building. those digests are themselves cached. in some cases Dune needs to drop some digest cache entries for things to be reliable, and this option makes Dune wait for the filesystem clock to advance so it doesn't need to drop anything. real talk: you should probably not care about this option, it's mostly useful for Dune developers to make Dune's tests of the digest cache more reproducible. iykyk 🧚

✨ COMMON OPTIONS ✨

these are the options that show up across all the commands, so they're basically the shared friend group 🌈

  • --always-show-command-line — always show the full command lines of programs executed by Dune. no mystery, we see everything.
  • --auto-promote — automatically promote files. it's basically like running dune promote after the build, but she does it herself ✨
  • --build-dir=FILE (absent DUNE_BUILD_DIR env) — specify the build directory. it's _build if you don't specify one.
  • --cache=VAL (absent DUNE_CACHE env) — enable or disable the Dune cache. one of disabled, enabled-except-user-rules or enabled. the default is enabled-except-user-rules.
  • --cache-check-probability=VAL (absent DUNE_CACHE_CHECK_PROBABILITY env) — check build reproducibility by re-executing randomly chosen rules and comparing their results against what's stored in the Dune cache. ⚠️ note: bumping up the probability of these checks slows down the build. the default probability is zero, meaning no rules get checked.
  • --cache-storage-mode=VAL (absent DUNE_CACHE_STORAGE_MODE env) — Dune cache storage mode, one of auto, hardlink or copy. the default is hardlink.
  • --config-file=FILE — load this configuration file instead of the default one.
  • --debug-backtraces — always print exception backtraces. when things go wrong we want the FULL story 😭
  • --debug-dependency-path — if there's an error, print the dependency path from the targets on the command line all the way back to the rule that failed.
  • --debug-package-logs (absent DUNE_DEBUG_PACKAGE_LOGS env) — always print the standard logs when building packages.
  • --default-target=TARGET (absent=@@default) — set 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 entirely.
  • --disable-promotion (absent DUNE_DISABLE_PROMOTION env) — disable all promotion rules.
  • --display=MODE — control the display mode of Dune. see dune-config(5) for more details. valid values for this option are progress, verbose, short, quiet or tui.
  • --dump-gc-stats=FILE — dump the garbage collector stats into a file once the build is complete.
  • --help[=FMT] (default=auto) — show this help in format FMT. FMT must 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 — ignore rules with (mode promote), except 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) — enable instrumentation by BACKENDS. BACKENDS is a comma-separated list of library names, and each one of them must declare an instrumentation backend.
  • -j JOBS (absent DUNE_JOBS env) — 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).
  • --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 bestie, that can be a real problem 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 as well, so you're sure commands get printed before they're executed.
  • --no-config — do not load the configuration file.
  • --no-print-directory — suppress the Entering directory messages.
  • --only-packages=PACKAGES — ignore stanzas that refer to a package that isn't 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 in order to build only what's necessary when your project contains multiple packages, and also to get reproducible builds. periodt.
  • --pkg=VAL — enable or disable package management. the default behaviour depends on whether a lock directory exists.
  • --profile=VAL (absent DUNE_PROFILE env) — select the build profile, for instance dev or release. the default is dev.
  • --promote-install-files[=VAL] (default=true) — promote any generated <package>.install files to the source tree.
  • --release — put dune into a reproducible release mode. 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, because -p implies this option.

  • --require-dune-project-file[=VAL] (default=true) — fail if a dune-project file is missing.
  • --root=DIR (absent DUNE_ROOT env) — use this directory as the workspace root instead of guessing it. note that this option doesn't change how targets given on the command line are interpreted. it's only intended for scripts.
  • --store-orig-source-dir (absent DUNE_STORE_ORIG_SOURCE_DIR env) — store the original source location in dune-package metadata.
  • --target-exec=TOOLCHAIN=CMD (absent DUNE_TARGET_EXEC env) — wrapper command for running target binaries when cross-compiling. format: TOOLCHAIN=CMD (e.g., 'windows=wine').
  • --terminal-persistence=MODE — change 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 — output trace data in catapult format (compatible with chrome://tracing). shine bright ✨
  • --verbose — same as --display verbose.
  • --version — show version information.
  • --watch-exclusions=REGEX — adds a POSIX regular expression that will exclude matching directories from dune build --watch. the option --watch-exclusions can be repeated to add multiple exclusions, and semicolons can also be used as a separator. if no exclusions are provided, 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) — use this specific workspace file instead of looking it up.
  • -x VAL (absent DUNE_CROSS_TARGET env) — cross-compile using this toolchain.

✨ MORE HELP ✨

use dune COMMAND --help for help on a single command. one command at a time, we keep it focused 💅

✨ EXIT STATUS ✨

dune test exits with:

  • 0 — on success. slay 🎀
  • 1 — if an error happened. 💀
  • 130 — if it was interrupted by a signal.

🌈 ENVIRONMENT 🌈

okay bestie, these are the lil environment variables that lowkey control how test behaves when it runs. set them, unset them, whatever — they're the backstage crew of your build 💅

  • DUNE_BUILD_DIR — the build directory you want. if you don't say anything it's just _build, no biggie.
  • DUNE_CACHE — turns the Dune cache on or off. pick ONE of: disabled, enabled-except-user-rules, or enabled. the default is enabled-except-user-rules. ✨
  • DUNE_CACHE_CHECK_PROBABILITY — this one makes Dune double-check that your builds are actually reproducible, by re-running randomly chosen rules and comparing what comes out against what's sitting in the Dune cache. ⚠️ heads up though: the higher you crank the probability, the slower your build gets. default probability is zero, meaning literally no rules get checked. so by default, none of that is happening.
  • DUNE_CACHE_STORAGE_MODE — how the Dune cache stores stuff. 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. yes, always. 🫶
  • DUNE_DIFF_COMMAND — the shell command used to diff files. pass - to disable printing the diff entirely.
  • DUNE_DISABLE_PROMOTION — kills all promotion rules. gone. bye. 💀
  • DUNE_INSTRUMENT_WITH — enable instrumentation via BACKENDS. BACKENDS is a comma-separated list of library names, and each one of them has to declare an instrumentation backend. no faking it, they gotta actually declare it.
  • DUNE_JOBS — don't run more than JOBS commands at the same time. JOBS has to be a positive integer, or auto to auto-detect your number of cores (which is the default, bestie — she auto-detects).
  • DUNE_PROFILE — the build profile. dev if you didn't specify anything, or release if -p is set. 🦋
  • DUNE_ROOT — use this directory as the workspace root instead of Dune going around guessing it. 📌 note: this option does not change how targets given on the command line get interpreted. it's only meant for scripts, iykyk.
  • DUNE_SANDBOX — the sandboxing mode to use by default. (peep --sandbox for the deets)
  • DUNE_STORE_ORIG_SOURCE_DIR — store the original source location in dune-package metadata.
  • DUNE_TARGET_EXEC — a wrapper command for running target binaries when you're cross-compiling. format: TOOLCHAIN=CMD (e.g., 'windows=wine'). 🍓
  • DUNE_WORKSPACE — use this specific workspace file instead of Dune going and looking one up.

🌸 BUGS 🌸

found something cursed? 😭 check the bug reports at https://github.com/ocaml/dune/issues — go tell the maintainers, they wanna know.

👑 SEE ALSO 👑

  • dune(1) — the main character herself 💖

and that's a wrap on the whole page, bestie!! 🎀 this was Dune 3.24.1's DUNE-TEST(1) manpage, and yes she ate, no crumbs. go forth and test with confidence. periodt. 💅✨

📦 where this page comes from