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
Build incomplete (process crashed)	<testcase> with <error>
Cached or substituted (no build needed)	<testcase> with <skipped>
Nix error messages	<system-err> at suite level

Example Report

<?xml version="1.0" encoding="utf-8" ?>
<testsuites>
    <testsuite
        name="nix-build"
        tests="3"
        failures="1"
        errors="0"
        skipped="1"
        time="42.0"
    >
        <testcase name="hello" time="12.5">
            <system-out>building '/nix/store/...-hello.drv'...</system-out>
        </testcase>
        <testcase name="goodbye" time="0.0">
            <skipped message="Cached or substituted" />
        </testcase>
        <testcase name="failing-pkg" time="29.5">
            <failure message="Build failed with code 1">
        <![CDATA[error: builder for '/nix/store/...-failing-pkg.drv' failed]]>
      </failure>
        </testcase>
        <system-err>error: some messages from nix</system-err>
    </testsuite>
</testsuites>

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

# Capture build output to a file
nix build --log-format internal-json -v --print-build-logs --no-link .#pkg1 2> build.log

# Later, translate it
cat build.log | junix translate -o report.xml

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.

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

# Build with a store path
junix build .#pkg1 --store /nix/store/... -o report.xml

The --store option adds a Nix store path to the report metadata.

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
junix check -o report.xml

# Filter by architecture
junix check --build-arch x86_64-linux --eval-arch x86_64-linux -o report.xml

How Check Discovery Works

1. Junix runs nix flake show --json to list all outputs
2. It filters for checks outputs matching the requested architectures
3. Each check is built with nix build --log-format internal-json
4. Results are collected into a single JUnit report

Controlling Log Verbosity

Nix has multiple log levels. Use -v flags to control what appears in the report:

# Errors only (default)
junix build .#pkg1 -o report.xml

# Info messages included
junix build .#pkg1 -v -o report.xml

# Chatty output (build phases, progress)
junix build .#pkg1 -vv -o report.xml

# Everything (debug-level detail)
junix build .#pkg1 -vvv -o report.xml

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