malpercio.dev
An easy-to-host PDS on the ATProtocol, MacOS. Grandma-approved.
docs: add test plan for MM-64 Nix flake + devenv dev shell
+106
+106
docs/test-plans/2026-03-07-MM-64.md
+106
docs/test-plans/2026-03-07-MM-64.md
···
1
+
# Human Test Plan: MM-64 Nix Flake + devenv Dev Shell
2
+
3
+
**Branch:** MM-64
4
+
**Base commit:** 0638285
5
+
**HEAD commit:** 1cc5cbb
6
+
**Generated:** 2026-03-07
7
+
8
+
---
9
+
10
+
## Prerequisites
11
+
12
+
- macOS machine with Nix installed (multi-user or single-user)
13
+
- The `ezpds` repository cloned and checked out at the MM-64 branch (commit `1cc5cbb` or later)
14
+
- `direnv` installed and hooked into the user's shell (for HV-3)
15
+
- Access to a Linux x86_64 machine or CI runner with Nix installed (for HV-1)
16
+
- `rustup` installed outside of Nix (for HV-2)
17
+
- All automated operational tests passing
18
+
19
+
**Note:** All `nix develop` commands require the `--impure` flag due to devenv's requirement to access `$PWD`. Without it, devenv fails with "devenv was not able to determine the current directory".
20
+
21
+
---
22
+
23
+
## Phase 1: Static File Verification
24
+
25
+
| Step | Action | Expected |
26
+
|------|--------|----------|
27
+
| 1.1 | Open `flake.nix` and inspect the `outputs` attribute | Only `devShells` is defined. No `packages`, `nixosModules`, `nixosConfigurations`, or other outputs present. |
28
+
| 1.2 | Open `flake.nix` and inspect the `inputs.systems` attribute | Set to `github:nix-systems/default`, which provides `aarch64-darwin`, `x86_64-darwin`, `x86_64-linux`, and `aarch64-linux`. |
29
+
| 1.3 | Open `rust-toolchain.toml` | Contains `channel = "stable"` and `components = ["rustfmt", "clippy", "rust-analyzer"]`. |
30
+
| 1.4 | Open `devenv.nix` | Contains `languages.rust.enable = true`, `toolchainFile = ./rust-toolchain.toml`, and packages list with `just`, `cargo-audit`, `sqlite`, `pkg-config`. Also sets `LIBSQLITE3_SYS_USE_PKG_CONFIG = "1"`. |
31
+
| 1.5 | Open `.envrc` | Contains exactly `use flake` (one line). |
32
+
| 1.6 | Run `git status` from repo root | `.envrc`, `flake.nix`, `devenv.nix`, `rust-toolchain.toml`, `flake.lock`, `.gitignore` are all tracked (not untracked or modified). |
33
+
34
+
---
35
+
36
+
## Phase 2: Operational Verification (macOS)
37
+
38
+
| Step | Action | Expected |
39
+
|------|--------|----------|
40
+
| 2.1 | `nix develop --impure --command bash -c 'echo "shell activated"'` | Prints "shell activated" and exits with code 0. devenv task output may appear on stderr (normal). |
41
+
| 2.2 | `nix develop --impure --command bash -c 'rustc --version'` | Prints `rustc 1.94.0 (...)` or a similar stable version. No "nightly" or "beta" in the output. |
42
+
| 2.3 | `nix develop --impure --command bash -c 'cargo --version && rust-analyzer --version && cargo clippy --version && rustfmt --version && just --version && cargo audit --version'` | All six commands succeed (exit 0). Each prints a version string. |
43
+
| 2.4 | `nix develop --impure --command bash -c 'sqlite3 --version && pkg-config --libs sqlite3'` | sqlite3 prints a version (3.x.x). pkg-config prints `-L/nix/store/.../lib -lsqlite3`. Both succeed. |
44
+
| 2.5 | `nix develop --impure --command bash -c 'echo $LIBSQLITE3_SYS_USE_PKG_CONFIG'` | Prints `1`. |
45
+
46
+
---
47
+
48
+
## End-to-End: Fresh Clone to Working Dev Shell
49
+
50
+
**Purpose:** Validates that a new contributor can go from `git clone` to a fully working development environment with zero manual dependency installation beyond Nix itself.
51
+
52
+
1. Clone the repository to a temporary directory: `git clone <repo-url> /tmp/ezpds-test && cd /tmp/ezpds-test && git checkout MM-64`
53
+
2. Run `nix develop --impure --command bash -c 'rustc --version && cargo --version && just --version && sqlite3 --version'`
54
+
3. **Expected:** First run may take several minutes (downloading Nix store paths). All four commands succeed. The Rust version is stable.
55
+
4. Run `nix develop --impure --command cargo check` from the repo root.
56
+
5. **Expected:** Cargo resolves dependencies and type-checks the workspace. Exit code 0. Confirms the toolchain, sqlite3 headers, and pkg-config all integrate correctly for an actual build.
57
+
6. Clean up: `rm -rf /tmp/ezpds-test`
58
+
59
+
---
60
+
61
+
## End-to-End: direnv Integration
62
+
63
+
**Purpose:** Validates that `.envrc` + `use flake` provides automatic shell activation when entering the project directory.
64
+
65
+
1. Ensure direnv is installed: `direnv version` (should print a version).
66
+
2. Ensure direnv is hooked into your shell. For zsh, verify `eval "$(direnv hook zsh)"` is in `~/.zshrc`. For bash, verify `eval "$(direnv hook bash)"` is in `~/.bashrc`.
67
+
3. Navigate to repo root: `cd /path/to/ezpds`
68
+
4. Run `direnv allow` to approve the `.envrc` file.
69
+
5. Navigate away: `cd /tmp`
70
+
6. Navigate back: `cd /path/to/ezpds`
71
+
7. **Expected:** direnv prints loading/activation messages. After activation completes, run `which rustc` — it should point to a path inside `/nix/store/`, not a system rustc.
72
+
8. Run `rustc --version` — should match the stable version seen in Phase 2 tests.
73
+
74
+
---
75
+
76
+
## Human Verification Required
77
+
78
+
| ID | Criterion | Why Manual | Steps |
79
+
|----|-----------|------------|-------|
80
+
| HV-1 | MM-64.AC1.2: Dev shell activates on Linux (x86_64-linux) | Cannot test on macOS; requires a Linux machine or CI runner | On an x86_64-linux machine with Nix installed, clone the repo, checkout MM-64, and run `nix develop --impure --command bash -c 'rustc --version && echo "Linux shell OK"'`. Expected: exit code 0, stable rustc version printed, "Linux shell OK" printed. |
81
+
| HV-2 | MM-64.AC3.2: rustup reads rust-toolchain.toml without Nix | Must run outside the Nix shell on a machine with rustup installed | 1. Ensure rustup is installed (`rustup --version` outside any Nix shell). 2. From repo root, without entering `nix develop`, run `rustup show`. 3. Expected: output includes "stable" as the active toolchain, references `rust-toolchain.toml` as the override source, and shows a Rust version consistent with the stable channel. |
82
+
| HV-3 | MM-64.AC4.2: direnv activates shell on `cd` | Requires an interactive shell session with direnv hooked in | See "End-to-End: direnv Integration" above. Key pass condition: after `direnv allow` and re-entering the directory, `which rustc` resolves to a `/nix/store/` path. |
83
+
84
+
---
85
+
86
+
## Traceability
87
+
88
+
| Acceptance Criterion | Automated | Manual Step |
89
+
|----------------------|-----------|-------------|
90
+
| MM-64.AC1.1: nix develop succeeds on macOS | PASS | Phase 2, Step 2.1 |
91
+
| MM-64.AC1.2: nix develop succeeds on Linux | N/A | HV-1 |
92
+
| MM-64.AC2.1: rustc is stable | PASS | Phase 2, Step 2.2 |
93
+
| MM-64.AC2.2: cargo available | PASS | Phase 2, Step 2.3 |
94
+
| MM-64.AC2.3: rust-analyzer available | PASS | Phase 2, Step 2.3 |
95
+
| MM-64.AC2.4: clippy available | PASS | Phase 2, Step 2.3 |
96
+
| MM-64.AC2.5: rustfmt available | PASS | Phase 2, Step 2.3 |
97
+
| MM-64.AC2.6: just available | PASS | Phase 2, Step 2.3 |
98
+
| MM-64.AC2.7: cargo-audit available | PASS | Phase 2, Step 2.3 |
99
+
| MM-64.AC2.8: sqlite3 + pkg-config | PASS | Phase 2, Step 2.4 |
100
+
| MM-64.AC3.1: Rust version matches rust-toolchain.toml | PASS | Phase 2, Step 2.2 |
101
+
| MM-64.AC3.2: rustup reads rust-toolchain.toml | N/A | HV-2 |
102
+
| MM-64.AC4.1: .envrc tracked with `use flake` | PASS | Phase 1, Step 1.5 |
103
+
| MM-64.AC4.2: direnv activates on cd | N/A | HV-3 |
104
+
| MM-64.AC5.1: flake.lock tracked by git | PASS | Phase 1, Step 1.6 |
105
+
| MM-64.AC6.1: no packages output | PASS | Phase 1, Step 1.1 |
106
+
| MM-64.AC6.2: no nixosModules output | PASS | Phase 1, Step 1.1 |