54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
|
# tests
|
||
|
|
|
||
|
|
Two ways to write tests, in one project.
|
||
|
|
|
||
|
|
```sh
|
||
|
|
cd examples/tests
|
||
|
|
crafter-build test
|
||
|
|
```
|
||
|
|
|
||
|
|
Layout:
|
||
|
|
|
||
|
|
```
|
||
|
|
mylib/MyMath.cppm # the library being tested
|
||
|
|
project.cpp # declares the library
|
||
|
|
|
||
|
|
tests/Smoke/main.cpp # zero-config test (no project.cpp)
|
||
|
|
tests/UnitMyMath/main.cpp # test that links MyMath and exercises it
|
||
|
|
tests/UnitMyMath/project.cpp # required for tests with deps
|
||
|
|
```
|
||
|
|
|
||
|
|
## Auto-discovery
|
||
|
|
|
||
|
|
Each `tests/<Name>/` directory becomes a test. Three layers, escalate only as needed:
|
||
|
|
|
||
|
|
1. **`tests/<Name>/main.cpp`** with no `project.cpp` — discovery synthesizes a Configuration. Top-level `*.cpp` files become implementations, `interfaces/*.cppm` become module interfaces. `Smoke` is this case.
|
||
|
|
2. **`tests/<Name>/project.cpp`** — full control. Use this when you need defines, dependencies, or non-default targets. `UnitMyMath` is this case (it depends on `MyMath`).
|
||
|
|
3. Folders starting with `_` or `.` are skipped (e.g. `tests/_shared/` for cross-test helpers).
|
||
|
|
|
||
|
|
## Test conventions
|
||
|
|
|
||
|
|
- Exit code `0` = pass, anything nonzero = fail, **`77` = skipped** (autoconf convention). Use `std::exit(77)` for runtime skips like "tool not on PATH".
|
||
|
|
- Each test runs in its own subprocess; a segfault doesn't take down the runner.
|
||
|
|
- Default timeout is 60 s (`crafter-build test --timeout=N` overrides).
|
||
|
|
- Filter by name: `crafter-build test 'Unit*'`. List without running: `crafter-build test --list`.
|
||
|
|
|
||
|
|
## Linking the parent project
|
||
|
|
|
||
|
|
`UnitMyMath/project.cpp` shows how a test links the project's own library:
|
||
|
|
|
||
|
|
```cpp
|
||
|
|
cfg.dependencies = { ParentLib("MyMath") };
|
||
|
|
```
|
||
|
|
|
||
|
|
`ParentLib("name")` looks up a `Configuration*` in the parent project (the root project's own config + its dependency graph) by `Configuration::name`. The fixture's project.cpp can omit `cfg.path`, `cfg.name`, etc. — the discovery loop fills folder-derived defaults.
|
||
|
|
|
||
|
|
## Cross-target test runs
|
||
|
|
|
||
|
|
Tests parse `--target=...` from the project args you pass on the command line:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
crafter-build test --target=x86_64-w64-mingw32 --runner=cmd:wine
|
||
|
|
```
|
||
|
|
|
||
|
|
`--runner=<spec>` overrides the per-target runner for this invocation. Useful specs: `local`, `cmd:<command>` (prefix-exec, e.g. `cmd:wine`, `cmd:qemu-aarch64`), `ssh:<host>[:<remoteDir>]`, `sshwin:<host>[:<remoteDir>]`. Or persist via env var: `CRAFTER_BUILD_RUNNER_<normalized_target>=<spec>`.
|