84 lines
2.6 KiB
Markdown
84 lines
2.6 KiB
Markdown
!!! 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:
|
|
|
|
1. **Unit & Integration Testing** — via [`nix-unit`](https://github.com/nix-community/nix-unit)
|
|
2. **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](https://martinfowler.com/articles/practical-test-pyramid.html):
|
|
|
|
* 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
|
|
|
|
[nix-unit](https://github.com/nix-community/nix-unit)
|
|
|
|
Example in: tests/eval-tests.nix
|
|
|
|
If you use flake-parts you can use the [native integration](https://flake.parts/options/nix-unit.html)
|
|
|
|
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`
|
|
|
|
```nix
|
|
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;
|
|
}
|
|
)
|
|
```
|