Skip to content

Latest commit

 

History

History
141 lines (115 loc) · 5.84 KB

reference.md

File metadata and controls

141 lines (115 loc) · 5.84 KB
Raw

Reference Documentation

Import the nix-vm-test to your Project

This project supports both flake-based workflows and non flake-based workflows.

Flake-based Workflows

Add the project to your flake.nix inputs to access the library from your flake outputs:

{
  inputs = {
    nix-vm-test = {
      url = "github:numtide/nix-vm-test";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, nix-vm-test }: {
    packages.x86_64-linux = let
      test = nix-vm-test.lib.x86_64-linux.debian."12" {
        (...)
      };
    in test.driver
  };
}

Non-Flake workflows

{ system ? "x86_64-linux", pkgs ? import <nixpkgs> { inherit system; }}:

let
  nix-vm-test-src = pkgs.fetchFromGitHub {
    owner = "numtide";
    repo = "nix-vm-test";
    # Replace this commit rev with the one pointed by the current main branch.
    rev = "e9df86d6275c5cda31c8bf3e7103e6c7c9e6fdad";
    sha256 = "sha256-NEpnmdhF5roYluocBmfpTjcg5giWtIXCMbsJFxTnNkM=";
  };
  nix-vm-test = import "${nix-vm-test-src}/lib.nix" {
    inherit system;
    nixpkgs = <nixpkgs>;
  };
  test = nix-vm-test.debian."12" {
    (...)
  };
in test.driver

Note: For a real-world deployment, you would probably want to pin Nixpkgs to a particular version, instead of using the one coming from your host path.

API

Inputs

The API consists consists roughly of two parts:

$ROOT.$DISTRIBUTION {
  $INPUTS
}

Where $ROOT will be nix-vm-test.lib.x86_64-linux on a flake-based setup.

Where $DISTRIBUTION is a $NAME.$VERSION couple. Here's the currently supported name/version couples:

Name Version
debian "12"
debian "13"
ubuntu "20_04"
ubuntu "22_04"
ubuntu "22_10"
ubuntu "23_04"
ubuntu "23_10"
fedora "38"
fedora "39"

Inputs

A Nix attribute set, as described in the Nix manual, is used to configure the VM test. The API is consistent across all the supported distributions.

For instance:

{
  diskSize = "+2M";
  sharedDirs = {
    shareName = {
      source = "/home/numtide/share";
      target = "/mnt";
    };
  };
  testScript = ''
    vm.wait_for_unit("multi-user.target")
    vm.succeed("apt-get update")
  '';
}

Where:

Attribute Name Description Example
diskSize Resize the guest root partition to a new size. That size can be either absolute (EG. 2G, 800M) or relative to the original size (EG. +500M, +2G) +2G
sharedDirs This attribute set describes the host directories that will be mounted to the guest filesystem. source being the host directory, target being the path we want to mount the directory on the VM. See above example
testScript A Python script used to orchestrate the integration test. This is compatible with NixOS tests. You can have a look at the relevant NixOS manual section to get the reference documentation of the available methods. See above example

Outputs

let
vmTest = nix-vm-test.debian."12" {
  diskSize = "+2M";
  sharedDirs = {
    shareName = {
      source = "/home/numtide/share";
      target = "/mnt";
    };
  };
  testScript = ''
    vm.wait_for_unit("multi-user.target")
    vm.succeed("apt-get update")
  '';
  };
interactive = vmTest.driverInteractive;
driver = vmTest.driver;
driverInSandbox = vmTest.sandbox;
in ...
Output "Path" Description
driver Run the test non-interactively. The VM will be able to reach the internet via a NAT interface with the host. This is likely the mode you want to use on your CI.
driverInteractive Run the test interactively. An interactive IPython console will open. You can interactively run the Python commands through this console. A qemu window also opens up, allowing you to directly interact with the VM shell. You can log in to the VM through the root account with an empty password.
sandbox Run the test non-interactively in the Nix sandbox. ⚠️ The Nix sandbox completely isolate the VM. You won't be able to have any network access, reach the Internet or use the host mounts with that mode