!!! Danger "Experimental" This service is for demonstration purpose only and may change in the future.
The Hello-World Clan Service is a minimal example showing how to build and register your own service.
It serves as a reference implementation and is used in clan-core CI tests to ensure compatibility.
What it demonstrates
- How to define a basic Clan-compatible service.
- How to structure your service for discovery and configuration.
- How Clan services interact with nixos.
Testing
This service demonstrates two levels of testing to ensure quality and stability across releases:
- Unit & Integration Testing — via
nix-unit - End-to-End Testing — via NixOS VM tests, which we extended to support container virtualization for better performance.
We highly advocate following the Practical Testing Pyramid:
- Write unit tests for core logic and invariants.
- Add one or two end-to-end (E2E) tests to confirm your service starts and behaves correctly in a real NixOS environment.
NixOS is untyped and frequently changes; tests are the safest way to ensure long-term stability of services.
/ \
/ \
/ E2E \
/-------\
/ \
/Integration\
/-------------\
/ \
/ Unit Tests \
-------------------
nix-unit
We highly advocate the usage of
Example in: tests/eval-tests.nix
If you use flake-parts you can use the native integration
If nix-unit succeeds you'r nixos evaluation should be mostly correct.
!!! Tip - Ensure most used 'settings' and variants are tested. - Think about some important edge-cases your system should handle.
NixOS VM / Container Test
!!! Warning "Early Vars & clanTest" The testing system around vars is experimental
`clanTest` is still experimental and enables container virtualization by default.
This is still early and might have some limitations.
Some minimal boilerplate is needed to use clanTest
nixosLib = import (inputs.nixpkgs + "/nixos/lib") { }
nixosLib.runTest (
{ ... }:
{
imports = [
self.modules.nixosTest.clanTest
# Example in tests/vm/default.nix
testModule
];
hostPkgs = pkgs;
# Uncomment if you don't want or cannot use containers
# test.useContainers = false;
}
)