Manual Test Cases

Run these against the extension loaded from Zig.novaextension/ with Nova in development mode. Each case lists the example project to open (under examples/), the steps to follow, and the expected result.

Setup

Before running any case:

Confirm the extension is active: Nova → Extensions → Extension Library → Zig shows as installed and enabled.
Confirm zig and zls are on PATH (or configured in global preferences).
Unless stated otherwise, open the project folder directly as a Nova workspace (not a single file).

T01 — Activation

Project: any .zig file or workspace containing one

| Step | Expected | |---|---| | Open a .zig file cold (no prior Nova session) | Extension Console shows ZLS starting; no error dialogs | | Check the task list | Current Zig File is present | | Open a workspace with build.zig | After a few seconds, Zig Build: \ tasks appear | | Open a folder with no .zig files | Extension does not activate; no ZLS process |

T02 — Syntax highlighting

Project: examples/snippets

Open each file and verify highlighting is applied:

| File | Check | |---|---| | syntax-tour.zig | Keywords (fn, const, pub), string literals, comments, numeric literals all coloured distinctly | | fibonacci.zig | Function signatures, control flow (if, while), types (u64) highlighted | | error-example.zig | Error set declarations, try, catch highlighted | | examples/zon-examples/full-types.zon | .field = value pairs highlighted; strings and numbers coloured | | examples/zon-examples/invalid.zon | File opens without Nova crashing |

T03 — Code folding

Project: examples/snippets/syntax-tour.zig

| Step | Expected | |---|---| | Click the fold widget next to a fn body | Function body collapses | | Click the fold widget next to a struct or union | Declaration collapses | | Click the fold widget next to a if/for/while block | Block collapses |

T04 — ZLS: completion and hover

Project: examples/multi-step (open workspace root)

| Step | Expected | |---|---| | Open src/main.zig, type std. | Completion popover appears with std members | | Hover over std.debug.print | Documentation tooltip appears | | Place cursor on a symbol and press ⌥F12 (Find References) or use the menu | References panel lists results | | Place cursor on a function call and press ⌘↓ (Go to Definition) | Navigates to the definition site | | Save a file with trailing whitespace | File is formatted on save (if Build On Save is off, trigger Format Document manually) |

T05 — ZLS: inline diagnostics

Project: examples/snippets/error-example.zig (open as a single file)

| Step | Expected | |---|---| | Open the file | ZLS highlights the intentional error with a red underline | | Hover over the underlined region | Error message appears in the tooltip | | Fix the error and save | Red annotation disappears |

T06 — Auto-discovered tasks: basic

Project: examples/multi-step

| Step | Expected | |---|---| | Open the workspace | Task list eventually contains Zig Build: install, run, test, check-fmt, gen-docs, run_server, bench, release-macos | | Select Zig Build: run and press ▶ | zig build run executes; output appears in the task report | | Select Zig Build: bench and press ▶ | zig build bench executes successfully | | Select Zig Build: check-fmt and press ▶ | Exits cleanly (sources are already formatted) |

T07 — Auto-discovered tasks: cache invalidation

Project: examples/multi-step

| Step | Expected | |---|---| | Note the current discovered step list | Baseline | | Add a new step to build.zig (e.g. a blank b.step("smoke", "…")) and save | Within a few seconds the task list updates; Zig Build: smoke appears | | Revert the change and save | Zig Build: smoke disappears from the list |

T08 — Auto-discovered tasks: discovery disabled

Project: examples/multi-step

| Step | Expected | |---|---| | Open Project Settings → Zig → Tasks → Discover Build Steps and set to Disabled | Zig Build: \ tasks all disappear from the list | | Current Zig File task | Still present and functional | | Re-enable discovery | Zig Build: \ tasks reappear |

T09 — Current Zig File: run

Project: examples/snippets/fibonacci.zig (open as a single file, or with the file active in any workspace)

| Step | Expected | |---|---| | Select Current Zig File and press ▶ | zig run fibonacci.zig executes; program output appears in the task report | | Switch to a different .zig file | The task now targets the new file (name in the task report changes) |

T10 — Current Zig File: clean

Project: examples/multi-step, open src/main.zig

| Step | Expected | |---|---| | Ensure .zig-cache exists in examples/multi-step/ (run any build first) | Baseline | | Select Current Zig File and trigger Clean | .zig-cache and zig-out inside examples/multi-step/ are removed; no warning dialog |

T11 — Zig Package: build and run

Project: examples/multi-step, using the pre-configured task in .nova/Tasks/Zig Package.json (Run Step = run)

| Step | Expected | |---|---| | Press ⌘B (Build) | zig build runs; exits 0; binary appears in zig-out/bin/ | | Press ▶ (Run) | zig build run runs; program output appears in task report | | Set Optimize to ReleaseFast and press ▶ | Command contains -Doptimize=ReleaseFast (visible in task report header or Extension Console) | | Set Target to aarch64-macos and press ⌘B | Command contains -Dtarget=aarch64-macos | | Add verbose to User Options and press ▶ | Command contains -Dverbose | | Add --verbose to Build Arguments and press ▶ | Command contains --verbose after the -D flags | | Add --help to Program Arguments and press ▶ | -- separator and --help appear after the step name | | Set Console to External Terminal and press ▶ | macOS Terminal opens a new window/tab and runs the program |

T12 — Zig Package: build-options project

Project: examples/build-options

| Step | Expected | |---|---| | Create a Zig Package task with Run Step blank | ▶ runs zig build; program prints using the default option values | | Add a User Option matching one of the options declared in build.zig | Re-run; program output reflects the new value |

T13 — Zig Test: all tests

Project: examples/test-suite, using one of the pre-configured tasks

| Step | Expected | |---|---| | Select Zig Test (all) and press ▶ | zig build test runs; both math and strings tests pass; no inline errors in editor | | Select Zig Test (all) and press ⌘B | Same command without --summary or --test-filter; exits 0 | | Set Summary to All and press ▶ | Output is more verbose (every step printed) |

T14 — Zig Test: inline error annotations

Project: examples/test-suite

| Step | Expected | |---|---| | Introduce a deliberate test failure in src/math.zig (e.g. change an expected value) and save | | | Run Zig Test (all) | Task exits non-zero; the failing line in math.zig gets a red gutter annotation | | Click the annotation | Error message is shown | | Revert the change and re-run | Annotation clears |

T15 — Zig Watch

Project: examples/multi-step, pre-configured Zig Watch task

| Step | Expected | |---|---| | Press ⌘B (Build) | zig build --watch starts; task report shows initial build output and then idles | | Edit src/lib.zig (e.g. change a return value) and save | Zig detects the change and rebuilds automatically; new output appears in the task report | | Stop the task | Process terminates cleanly | | Set Debounce to 500 and restart | --debounce 500 appears in the command | | Set Incremental to On and restart | -fincremental appears in the command |

T16 — Zig Debug: auto-detection

Project: examples/multi-step — create a Zig Debug task with Program blank

| Step | Expected | |---|---| | Press ▶ (Run/Debug) | Extension reads build.zig.zon, finds .name = "multi-step", probes zig-out/bin/multi-step | | If binary exists (run Build first) | Debugger launches and the program runs under lldb-dap | | If binary does not exist | Warning dialog asks you to fill in the Program field manually |

T17 — Zig Debug: breakpoints

Project: examples/multi-step — Zig Debug task, Optimize = Debug

| Step | Expected | |---|---| | Set a breakpoint in src/main.zig by clicking the gutter | Red dot appears | | Press ▶ | Program pauses at the breakpoint; Variables panel shows local state | | Step over (F10) | Execution advances one line | | Continue (F5) | Program runs to completion or the next breakpoint |

T18 — Zig Debug: stop on entry

Project: examples/multi-step — Zig Debug task

| Step | Expected | |---|---| | Enable Stop On Entry | | | Press ▶ | Debugger pauses at the very first instruction before any user code runs |

T19 — Clean: safety guards

Create a Zig Package task in any project and test each guard:

| Scenario | How to trigger | Expected | |---|---|---| | Working Directory = / | Set the field to / | Clean shows a warning and does nothing | | Working Directory = $HOME | Set the field to your home directory | Clean shows a warning and does nothing | | Working Directory outside workspace | Set an absolute path outside the open folder | Clean shows a warning and does nothing | | Valid cwd | Normal configuration | .zig-cache, zig-cache, zig-out are removed |

T20 — Clean: zig build uninstall

Project: a project whose build.zig registers an uninstall step (add one temporarily if needed)

| Step | Expected | |---|---| | Run Build once to populate the step cache | | | Trigger Clean | Extension Console shows zig build uninstall was called before rm -rf |

T21 — Monorepo: sub-package working directory

Project: examples/monorepo (open workspace root)

| Step | Expected | |---|---| | Discover tasks at root | Zig Build: run, test-all, gen-docs appear | | Create a Zig Package task; set Working Directory to packages/alpha | Build/Run operates on packages/alpha/build.zig | | Create a Zig Test task; set Working Directory to packages/beta | Tests run from packages/beta/ |

T22 — Inline compiler errors

Project: examples/snippets/error-example.zig via a Zig Package or Current Zig File task

| Step | Expected | |---|---| | Run the task against a file with a compile error | Error annotation appears at the correct line and column in the editor | | The annotation text | Matches the error: message from the compiler | | Fix the error and re-run | Annotation clears |

T23 — Settings: custom executable paths

Scope: Nova Preferences → Extensions → Zig

| Step | Expected | |---|---| | Set Zig Executable to an absolute path (e.g. /usr/local/bin/zig) | Tasks use that binary instead of PATH discovery | | Set it to a non-existent path | First task run shows a warning about missing zig | | Clear the field | PATH discovery resumes |

T24 — Settings: workspace overrides global

Project: any workspace

| Step | Expected | |---|---| | Set a global preference (e.g. Discover Build Steps = disabled) | Workspace inherits; no discovered tasks | | In Project Settings, set Discover Build Steps to Enabled | Discovered tasks reappear for this workspace only | | Open a different workspace | Still uses the global disabled setting |