Gus's Blog

Integration testing with Nix

Wed, 20 May 2026 00:00:00 GMT

I’ve recently been working on a TypeScript client library (neoprom) for Prometheus, which makes it easier for developers to instrument code for gathering metrics. As part of this project, I want to have good tests that both cover the library’s internal logic, as well as make sure it works properly with Prometheus. So… what are the options?

Install Prometheus system-wide

Lots of problems: I’d rather not have it installed all the time, I’d have to wipe its database before running every test, and it’d be an extra setup step for new contributors with different steps depending on their OS (as well as their distro if on Linux).

Spin a container up and down

This would mean writing a messy Containerfile, and adding extra steps to the test script (start, stop, wipe state).

Or… I can take advantage of the existing test framework used for testing NixOS! Here’s a very basic example:

{ pkgs }:
pkgs.testers.runNixOSTest {
  name = "ping test";

  containers = {
    machine1 = { };
    machine2 = { };
  };

  testScript = ''
    start_all()
    machine1.succeed("ping -c 1 machine2")
    machine2.succeed("ping -c 1 machine1")
  '';
}

When ran, it starts two containers, then has them ping each other.

The true power of this tool comes with being able to assign each machine a NixOS configuration:

{
  pkgs,
  lib,
  src,
}:
pkgs.testers.runNixOSTest {
  name = "more advanced test";

  containers.app =
    { pkgs, ... }:
    {
      environment.systemPackages = [ pkgs.prometheus.cli ];
      systemd.services.metrics = {
        wantedBy = [ "multi-user.target" ];
        serviceConfig.ExecStart = "${lib.getExe pkgs.nodejs} ${src}/some-server.ts";
      };
      services.prometheus = {
        enable = true;
        # more configuration...
      };
    };

  testScript = ''
    start_all()
    app.wait_for_unit("metrics.service")
    app.wait_for_unit("prometheus.service")
    app.wait_for_open_port(9000)
    app.wait_for_open_port(9090)

    data = app.succeed("promtool query instant http://localhost:9090 some_total")
    # ...
  '';
}

The specific command to run the test depends on the project’s setup. You can look at my non-flake setup for inspiration, or take a peek at Jacek Galowicz’s work below (Nixcademy).

Thanks for reading :)

Resources

https://nixcademy.com/posts/faster-cheaper-nixos-integration-tests-with-containers/ (slides & example repo)

https://nixos.org/manual/nixos/unstable/#sec-nixos-tests

https://nix.dev/tutorials/nixos/integration-testing-using-virtual-machines.html

Run your own Matrix homeserver on NixOS

Mon, 16 Feb 2026 00:00:00 GMT

Due to current events, alternatives to Discord have been getting a lot of attention recently. As much as I would love for Matrix to succeed here, it isn’t ready for most non-technical users. However, if you want to tinker…

This guide assumes a few things:

You’ll be running the server on a computer that’s publically accessible over the internet
You have a domain that points to said machine
Said machine is running NixOS

Since “Matrix” is a protocol, there are several server implementations - with the most widely used (by far) being Synapse. It was the first implementation, and it’s used to host the official matrix.org server - however, it has performance issues and eats a bunch of RAM and CPU. The main alternative, which is what this guide will use, is Continuwuity¹.

Continuwuity is packaged in nixpkgs and already has a NixOS module, which makes the setup process just involve enabling the service and some settings:

let
    your-domain = "example.com";
in
services.matrix-continuwuity = {
    enable = true;

    settings.global = {
        server_name = your-domain;

        new_user_displayname_suffix = "";

        address = null;
        unix_socket_path = "/run/continuwuity/continuwuity.sock";

        well_known.client = "https://matrix.${your-domain}";
        well_known.server = "matrix.${your-domain}:443";

        # just in case!
        lockdown_public_room_directory = true;
        allow_room_creation = false;
        require_auth_for_profile_requests = true; # no user enumeration
        url_preview_domain_explicit_allowlist = [ "github.com" ];

        log = "INFO,conduwuit_core::matrix::state_res=off"; # cleaner logs
    };
  };

We also need to expose the server to the public internet. Caddy makes this super easy, handles TLS certificates automatically, etc.

let
    your-domain = "example.com";
in
services.caddy = {
    enable = true;
    virtualHosts = {
        "${your-domain}".extraConfig = ''
            reverse_proxy /.well-known/matrix/* unix//run/continuwuity/continuwuity.sock
        '';
        "matrix.${your-domain}".extraConfig = ''
            route {
                @api path /_matrix/* /_continuwuity/*
                reverse_proxy @api unix//run/continuwuity/continuwuity.sock
            }
        '';
    };
};
users.users.caddy.extraGroups = [ "continuwuity" ]; # give caddy access to continuwuity's unix socket
networking.firewall.allowedTCPPorts = [ 80 443 ];
networking.firewall.allowedUDPPorts = [ 443 ];

To test that the server is accessible to the wider network, you can use the Matrix Federation Tester.

Now that the server is up, running and working, you need a client to use to connect. I prefer Cinny since it’s a self-contained web application and has a good UI, but there are many others. You can use the official instance the developer runs at app.cinny.im, or deploy your own:

"matrix.${your-domain}".extraConfig = ''
    route {
        @api path /_matrix/* /_continuwuity/*
        reverse_proxy @api unix//run/continuwuity/continuwuity.sock

        root * ${
            pkgs.cinny.override {
                conf = {
                    defaultHomeserver = 0;
                    homeserverList = [ your-domain ];
                    allowCustomHomeservers = false;
                    featuredCommunities = {
                        openAsDefault = false;
                        spaces = [
                            "#community:matrix.org"
                            "#cinny-space:matrix.org"
                            "#space:continuwuity.org"
                            "#space:nixos.org"
                        ];
                        rooms = [ ];
                        servers = [
                            "matrix.org"
                            "mozilla.org"
                            "nixos.org"
                        ];
                    };
                };
            }
        }
        try_files {path} / index.html
        file_server
    }
'';

Now it’s time to register your account! Your client will ask for a registration token, which is in the service logs:

sudo journalctl -u continuwuity | grep "registration token"

If you run into any issues, the Continuwuity matrix space is super active and helpful. You might need to create an account on different server like matrix.org if your own isn’t fully set up yet :)

Of all the non-synapse servers - Dendrite is in maintenance mode, Conduit has less active development, and the primary maintainer of Tuwunel is banned by the Matrix Foundation ↩

Testing

Thu, 05 Feb 2026 00:00:00 GMT

This is a test blog post to make sure everything is working right!

console.log("hello!")

Gus's Blog

Integration testing with Nix

Resources

Run your own Matrix homeserver on NixOS

Footnotes

Testing