nim-testing

Files (3)

• SKILL.md
• block_test_pattern.md · references/
• ci_github_actions.md · references/

SKILL.md (first lines)

# Nim Testing

## Rules

### Use `block`-based tests with `doAssert`

Import `std/assertions`. Use `block` scopes with `doAssert` and `doAssertRaises`:

```nim
import std/assertions

block add_basic:
  doAssert add(1, 2) == 3, "add should sum positive integers"

block greet_empty:
  doAssert greet("") == "hello "

block parse_bad_input:
  doAssertRaises ValueError:
    discard parseThing("")
```

`doAssert` raises `AssertionDefect` on failure. `doAssertRaises` passes only when the requested exception type is raised; otherwise the test exits non-zero.

### Write unambiguous assertions

Use ordinary call syntax and grouped negation inside `doAssert`:

```nim
proc foo(x: int): int = x
proc same(x, y: int): bool = x == y

doAssert foo(1) == 1, "foo should return its argument"
doAssert same(1, 1), "same values should match"
doAssert not (foo(1) < 0), "foo should not return a negative value"
doAssert 4 notin @[1, 2, 3]
```

Avoid command-call syntax in assertions. `doAssert foo 1 == 1` can bind the
comparison to `foo`, and `doAssert same 1, 1` can bind the comma to `doAssert`.

### Project layout

```
project/
  src/
    mylib.nim
  tests/
    config.nims        # shared compiler switches
    tester.nim         # central test runner (auto-discovers t*.nim)
    tbasic.nim
    tedge.nim
    terrors.nim
```

Test files use `t` prefix: `tbasic.nim`, `tedge.nim`, `terrors.nim`, `tintegration.nim`.

### `tests/config.nims`

```nim
switch("path", "$projectdir/../src")
```

The compiler loads this config automatically when compiling files in `tests/`.

### `tests/tester.nim`

```nim
import std/os

proc fatal(msg: string) = quit "FAILURE " & msg

proc exec(cmd: string) =
  echo "Running: ", cmd
  if execShellCmd(cmd) != 0: fatal cmd

let testDir = getCurrentDir() / "tests"
for f in walkFiles(testDir / "t*.nim"):
  let name = f.extractFilename
  if name == "tester.nim":
    discard
  else:
    exec "nim c -r " & quoteShell(testDir / name)

echo "All test files completed."
```

Run from project root: `nim c -r tests/tester.nim`

New test files are auto-discovered — no runner edits needed.

### Shared Test Code

Keep test files self-contained when practical. If setup is repeated, extract domain helpers such as sample builders, temp-file setup, or fixture data.

## Workflow

1. **Set up layout.** Create `src/`, `tests/`, and `tests/config.nims`.
2. **Write test files.** Name files with `t` prefix. Use `block`, `doAssert`, and `doAssertRaises`.
3. **Create the runner.** Add `tests/tester.nim` with the auto-discover pattern.
4. **Run all configurations:**

   ```
   nim c -r tests/tester.nim
   nim c -d:release -r tests/tester.nim
   nim c -d:danger -r tests/tester.nim
   ```

5. **Run with ASan** if the project uses unsafe constructs. See "AddressSanitizer" below.
6. **Set up CI.** See `references/ci_github_actions.md`.

## Multi-configuration testing

| Mode                  | Overflow checks | Stack traces (file:line) |
|-----------------------|-----------------|--------------------------|
| default / `-d:debug`  | Yes             | Full                     |
| `-d:release`          | Yes             | Raising frame only       |
| `-d:danger`           | No              | Raising frame only       |

From Vyrnexis/nim-agent-template, MIT.

More from Vyrnexis/nim-agent-template