Skip to content

Usage Guide

Understanding the JUnit Output

Junix maps Nix build activities to JUnit test cases:

Nix build result JUnit element
Build succeeded <testcase> with <system-out> containing build logs
Build failed <testcase> with <failure> containing build logs
Eval failed <testcase> with <failure> and Nix error trace in <system-out>
Build incomplete (process crashed) <testcase> with <error>
Cached or substituted (no build needed) <testcase> with <skipped>
Nix error messages <system-err> on the first failing testcase

Example Report

Here is a real JUnit report from junix check on a flake with one passing and one failing check:

<?xml version="1.0" encoding="utf-8" ?>
<testsuites>
    <testsuite
        name="nix-eval.x86_64-linux"
        tests="2"
        failures="0"
        errors="0"
        skipped="0"
        time="0"
    >
        <testcase
            name="nix eval .#checks.x86_64-linux.passing"
            classname="/nix/store/xxx-passing-check.drv"
            time="0"
        >
            <system-out>/nix/store/xxx-passing-check.drv</system-out>
        </testcase>
        <testcase
            name="nix eval .#checks.x86_64-linux.failing"
            classname="/nix/store/yyy-failing-check.drv"
            time="0"
        >
            <system-out>/nix/store/yyy-failing-check.drv</system-out>
        </testcase>
    </testsuite>
    <testsuite
        name="nix-build.x86_64-linux"
        tests="2"
        failures="1"
        errors="0"
        skipped="0"
        time="0"
    >
        <testcase
            name="nix build .#checks.x86_64-linux.passing"
            classname="/nix/store/xxx-passing-check.drv"
            time="0"
        >
            <system-out>This check passes</system-out>
        </testcase>
        <testcase
            name="nix build .#checks.x86_64-linux.failing"
            classname="/nix/store/yyy-failing-check.drv"
            time="0"
        >
            <failure message="Build failed" type="failure" />
            <system-out>This check fails</system-out>
            <system-err>
                error: builder for '/nix/store/yyy-failing-check.drv' failed with exit
                code 1
            </system-err>
        </testcase>
    </testsuite>
</testsuites>

If a check fails to evaluate (builtins.tryEval returns success: false), the <system-out> of the failing eval testcase contains the Nix error trace for that check, captured by a follow-up nix eval --show-trace call. For example, a check defined as pkgs.runCommand "eval-fail-check" {} (throw "boom") produces:

<testcase name="nix eval .#checks.x86_64-linux.eval-fail" ...>
    <failure message="Build failed" type="failure" />
    <system-out>error:
       … while evaluating the 'drvPath' of derivation 'eval-fail-check'
         at /nix/store/.../lib/customisation.nix:415:11:
          414|         // {
          415|           drvPath =
             |           ^
          416|             assert condition;

       … while calling the 'throw' builtin
         at ./flake.nix:23:9:
           22|       eval-fail = pkgs.runCommand "eval-fail-check" {} (
           23|         throw "This check fails to evaluate"
             |         ^

       error: This check fails to evaluate
</system-out>
</testcase>

The report contains one <testsuite> per architecture per phase:

  • Eval suites (nix-eval.{arch}) — one testcase per check, with the derivation path in <system-out> on success, or <failure> and the Nix error trace in <system-out> if the check failed to evaluate.
  • Build suites (nix-build.{arch}) — one testcase per check, with build logs in <system-out> on success, <failure> on build failure, or <skipped> when the build was cached. A check whose eval already failed also appears here as <failure> (since the build can never succeed without a derivation) carrying the same eval error trace in <system-out>.

    The build suite can have more testcases than you have checks

    Nix builds whatever a check actually needs, not just the check itself. A NixOS system check pulls in dozens of supporting derivations — activate.drv, X-Restart-Triggers-dbus-broker.drv, and similar internals of the system closure — and each one that Nix actually builds becomes its own testcase, named after its store path rather than a check name.

    This is intentional: those builds really happened and really took time, so they belong in the report, not hidden from it. It only shows up when Nix has work to do — a fully cached run reports exactly one testcase per check, same as always, because nothing new gets built. Seeing 75 testcases for 41 checks one run and exactly 41 the next is expected, not a flaky report.

The <testcase> name in every JUnit suite is the exact command you would run to reproduce the work: nix eval <path>#checks.<arch>.<name> for eval suites, nix build <path>#checks.<arch>.<name> for build suites, and nix build <attr> for the build subcommand. This makes failures in CI reproducible by copy-paste.

Dependency failures

When a dependency fails, nix build --keep-going skips every check that needs it. Those checks are reported as <failure type="dependency"> with message="Dependency failed: <drv path>", naming the first dependency that broke (the root cause, since Nix reports failures in build order). Direct build failures keep type="failure" and message="Build failed", so CI viewers can tell them apart.

In the terminal summary they print as ✗ … (dep failed) in dim red, next to bold red for direct failures, green for successes and dim green for cached builds.

Timing

  • <testcase time> is the real wall-clock of that build, measured while Nix runs. It is 0 for cached builds and for checks that never started.
  • <testsuite time> is the sum of its testcases, the usual JUnit convention, so tools that add up testcase times (like GitLab) agree with it.
  • Nix does not report per-check eval times, so eval suites split the measured nix eval wall-clock among their checks. Checks that needed an extra nix eval --show-trace get that call's measured time.

Colored terminal summary

See the --color global switch in the CLI reference for the full description of the three modes (auto, yes, no) and the JUNIX_COLOR precedence rule (CLI > env > auto). When colors are enabled, the summary uses the following scheme:

  • blue for informational headers (e.g. eval {arch} ... N checks, ⬇ N path(s) downloaded)
  • green for passed checks
  • bold red for failed checks and the final FAILED line
  • red for the cached count line
  • dim green for per-check cached entries

Example output from a mixed run:

  ⬇ 3 path(s) downloaded
  ~ 1 build(s) cached
  ✓ checks.x86_64-linux.passing
  ✗ checks.x86_64-linux.failing

  FAILED (1/2):
    - checks.x86_64-linux.failing

translate: Parsing Existing Build Output

Use translate when you already have Nix build output and want to convert it to JUnit XML. This is useful when:

  • You want to capture output from a complex build script
  • You need to reprocess previously saved logs
  • You're integrating Junix into an existing pipeline
# Stream a live build into junix
nix build --log-format internal-json -v --print-build-logs --no-link .#pkg1 2>&1 | junix translate -o report.xml

# Or capture to a file and translate later
nix build --log-format internal-json -v --print-build-logs --no-link .#pkg1 2> build.log
cat build.log | junix translate -o report.xml

junix translate reads @nix JSON lines from stdin and writes the JUnit XML report to stdout (or to -o). While it reads, it immediately forwards non-@nix lines and Nix log messages that match the current verbosity to its own stderr, formatted in human-readable form. This lets you watch a long build live while still getting the report at the end.

Tip

Make sure to use --log-format internal-json when running Nix, otherwise Junix won't be able to parse the output.

build: Build and Report

Use build when you want Junix to drive the Nix build directly. This is the simplest way to get a JUnit report.

Each <testcase> in the JUnit report is named after the exact nix build command that would reproduce it (e.g. nix build nixpkgs#hello). A colorful summary is printed to stderr showing downloaded, cached, passed and failed builds, ending with PASSED (T evals, T builds) or FAILED (F/T evals, F/T builds) (F = failed, T = total).

# Build one or more packages
junix build .#pkg1 .#pkg2 -o report.xml

# Build with a remote store
junix build .#pkg1 --store ssh-ng://eu.nixbuild.net -o report.xml

# Pass extra flags to nix build after --
junix build nixpkgs#hello -- --no-link --rebuild

The --store option sets a remote build store (e.g. nixbuild.net). When this option is honoured by Nix (the Nix user must be trusted for the store setting), build logs from the remote arrive as structured protocol events and appear in <system-out> of the JUnit report. When Nix ignores --store and falls back to an SSH builder (e.g. configured in /etc/nix/machines), build logs arrive as plain text on stderr and are not included in the report. Those plain-text lines are only shown with -vv or higher.

check: Run All Flake Checks

Use check to run all checks defined in your flake. This is ideal for CI pipelines where you want to validate the entire project.

# Run all checks (eval all arches, build local only)
junix check -o report.xml

# Evaluate only specific architectures
junix check --eval-arch x86_64-linux --eval-arch aarch64-linux -o report.xml

# Build specific architectures (default: local only)
junix check --build-arch x86_64-linux -o report.xml

# Pass extra flags to nix build
junix check -- --no-link --rebuild

How Check Discovery Works

  1. Junix runs nix eval --json "path#checks" --apply with a Nix expression that evaluates each check using builtins.tryEval, so one eval failure does not abort the entire discovery.
  2. The expression returns a JSON list of objects with arch, name, drvPath, and error fields.
  3. Checks whose eval succeeded (drvPath is not null) are sent to nix build in the build phase.
  4. Checks whose eval failed are never sent to nix build — they are reported as build failures with the eval error message. builtins.tryEval swallows the Nix error trace and only returns success: false, so for each failing check junix runs a second nix eval --show-trace "path#checks.<arch>.<name>.drvPath" to capture the real trace. That trace becomes the error field in the JUnit <system-out> of the failing testcase. Only failing checks pay the extra round trip; healthy flakes run one eval.
  5. By default, only the local system checks are built. Use -b to override.

builtins.tryEval cannot catch errors raised by a derivation build triggered during evaluation (import-from-derivation) — such a failure crashes the whole bulk nix eval process instead of just the one check, and Nix reports it with an opaque, untraceable message. When that happens, check automatically retries the eval phase with --eval-individually, which isolates each check in its own nix eval process: the one check that can't evaluate still fails, but every other check reports normally instead of the whole run coming back empty.

Path handling

Junix passes the PATH argument to check directly to nix eval and nix build, without rewriting it. Like Nix itself, relative paths must start with ./ or be absolute. The default is .. If you pass a bare relative path (e.g. tests/sample-flake), Nix rejects it with its usual error message — Junix surfaces that error in the JUnit report as a build failure.

Summary output

The colorful summary on stderr has two sections: one for the eval phase (per architecture) and one for the build phase (per architecture). The final line uses separate counts for evals and builds:

eval x86_64-linux ... 2 checks
  ✓ nix eval .#checks.x86_64-linux.passing
  ✗ nix eval .#checks.x86_64-linux.failing
build x86_64-linux ... 2 checks
  ✗ nix build .#checks.x86_64-linux.failing
  ✓ nix build .#checks.x86_64-linux.passing (cached)

FAILED (1/2 evals, 1/2 builds)

Architecture flags

The -e/--eval-arch and -b/--build-arch flags are independent:

  • -e controls which architectures are evaluated (default: all)
  • -b controls which architectures are built (default: local only)

Passing -e aarch64-linux does NOT change the default of -b (still local). Passing -b aarch64-linux does NOT change the default of -e (still all).

Memory-constrained flakes

The default junix check discovery runs one nix eval [...magic...] flake#checks call that evaluates every check × arch in a single Nix process. That's efficient for small flakes, but can OOM on large ones, like those building full NixOS or derivations with hundreds of dependencies accross some arches. The symptom is a CI job that dies without junix ever printing a line similar to eval x86_64-linux ... 2 checks.

The -1/--eval-individually flag trades that for per-check isolation: junix runs just one nix eval to find all check names, and then evals each check individually, so the RAM peak is bounded by the closure of the largest single check — not the sum of all checks. The wall-clock cost is one Nix process per check (hundreds of milliseconds each), so a flake with hundreds of checks pays noticeable overhead. Use this only when the bulk path OOMs:

junix check -1o report.xml

Those per-check processes are mostly idle — waiting on the store, on substituter round trips and on import-from-derivation builds — so running several at once is a large win. It is not on by default, because you reached for -1 precisely when memory was scarce. Opt in when you have the headroom:

junix check -1 -o report.xml          # serial: 4m24s, 2.4 GB peak
junix check -1 -j 4 -o report.xml     # 2m04s, 3.8 GB peak

Growth is sublinear — the heavy checks do not all overlap, and a single eval already forks its own import-from-derivation builds — so there are diminishing returns: on that flake -j 8 bought 3 more seconds for 3 more GB. Measure on your own flake rather than copying a number; see --eval-jobs for why junix refuses to guess.

Without -1, -j defaults to 4 but barely matters: there it only fans out the nix eval --show-trace recovery for checks that already failed, which happens after the one big eval process has exited.

--eval-individually is orthogonal to -e and -b: it does not change which arches are evaluated or built, only how each check is evaluated. The JUnit structure is identical to the bulk path (per-arch nix-eval.<arch> and nix-build.<arch> suites, same reproducer testcase names, same drv path in <system-out>). Failing checks automatically get the real Nix error trace in their <system-out> — no second nix eval --show-trace round trip is needed, since each per-check call surfaces the trace directly.

Controlling Log Verbosity

See --verbose for what each -v level shows.

CI Integration

GitLab CI

test:
    script:
        - junix check -o report.xml
    artifacts:
        reports:
            junit: report.xml

Jenkins Pipeline

stage('Nix Build') {
  steps {
    sh 'junix build .#pkg1 -o report.xml'
  }
  post {
    always {
      junit 'report.xml'
    }
  }
}

GitHub Actions

- name: Run Nix checks
  run: junix check -o report.xml

- name: Upload JUnit report
  uses: dorny/test-reporter@v1
  if: success() || failure()
  with:
      name: Nix Build Results
      path: report.xml
      reporter: java-junit