Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cachix/devenv/llms.txt

Use this file to discover all available pages before exploring further.

Tests in devenv let you verify that your development environment is working as expected. You define test logic in the enterTest hook inside devenv.nix, then run devenv test to build the environment and execute your tests. If you have processes defined, devenv starts and stops them automatically around the test run.

​
Writing Your First Test

A simple test verifies that a package is present and returns the expected version:
devenv.nix
{ pkgs, ... }: {
  packages = [ pkgs.ncdu ];

  enterTest = ''
    ncdu --version | grep "ncdu 2.2"
  '';
}

$ devenv test
✓ Building tests in 2.5s.
• Running tests ...
Setting up shell environment...
Running test...
ncdu 2.2
✓ Running tests in 4.7s.
✓ Tests passed. in 0.0s.
By default, enterTest also detects if a .test.sh file exists in your project root and runs it.

​
Testing with Processes

If you have processes defined in your environment, they will be started before your tests run and stopped automatically afterward:
devenv.nix
{ pkgs, ... }: {
  services.nginx = {
    enable = true;
    httpConfig = ''
      server {
        listen 8080;
        location / {
          return 200 "Hello, world!";
        }
      }
    '';
  };

  enterTest = ''
    wait_for_port 8080
    curl -s localhost:8080 | grep "Hello, world!"
  '';
}

$ devenv test
✓ Building tests in 2.5s.
✓ Building processes in 15.7s.
• Starting processes ...• PID is 113105
• See logs:  $ tail -f /run/user/1000/nix-shell.upTad4/.tmpv25BxA/processes.log
• Stop:      $ devenv processes stop
✓ Starting processes in 0.0s.
• Running tests ...
Setting up shell environment...
Running test...
ncdu 2.2
✓ Running tests in 4.7s.
• Stopping process with PID 113105
✓ Tests passed. in 0.0s.

​
Helper Functions in enterTest

The following helper functions are available inside enterTest:
  • wait_for_port <port> <timeout> — waits until the given port is open before continuing

​
Using Tasks for Test Dependencies

For more complex test setups with dependencies and better control over parallelism, use tasks with the before attribute to hook into devenv:enterTest:
devenv.nix
{ pkgs, lib, config, ... }:

{
  tasks = {
    "myapp:test-setup" = {
      exec = "echo 'Preparing test fixtures...'";
      before = [ "devenv:enterTest" ];
    };
  };

  enterTest = ''
    echo "Running tests against prepared fixtures..."
  '';
}
Tasks registered before devenv:enterTest run first and can be parallelized, making them a good fit for seeding databases, generating fixtures, or waiting on external services.

​
Changing Environment During Tests

You can use config.devenv.isTesting to conditionally include or exclude processes and configuration depending on whether devenv test is running:
devenv.nix
{ pkgs, lib, config, ... }: {
  processes = {
    backend.exec = "cargo watch";
  } // lib.optionalAttrs (!config.devenv.isTesting) {
    frontend.exec = "parcel serve";
  };
}
This is useful when you want to skip resource-intensive development processes (like a frontend bundler watcher) during automated test runs.

​
CI Integration

Running devenv test in CI is the recommended way to verify your environment and run all checks, including:
  • Git hooks / pre-commit checks (if git-hooks are configured)
  • enterTest assertions
  • Process startup and readiness
A minimal CI step looks like: 
- name: Run devenv tests
  run: devenv test
Use devenv processes wait --timeout 120 in CI if you need to wait for processes to become ready before running additional steps outside of devenv test.

Build docs developers (and LLMs) love

Get started for freeTalk to us