test: clarify repo-level test layout (#170)

Author: benvinegar

AGENTS.md

@@ -56,7 +56,11 @@ CLI input
 - Colocate unit tests with the code they cover (`src/core/foo.ts` + `src/core/foo.test.ts`, `src/ui/AppHost.*.test.tsx`, `src/ui/lib/*.test.ts`).
 - Put shared unit-test helpers in `test/helpers/`.
 - Name test helpers so they explicitly include `Test` and are clearly test-only (`createTestDiffFile`).
-- Keep other repo-level `test/` files for cross-cutting integration, PTY/session, CLI transcript, and smoke coverage.
+- Use repo-level `test/` directories by intent:
+  - `test/cli/` for black-box CLI contract coverage.
+  - `test/session/` for daemon/session integration and end-to-end flows.
+  - `test/pty/` for PTY-backed live UI integration tests.
+  - `test/smoke/` for opt-in terminal transcript smoke coverage.
 
 ## code comments
 
@@ -110,7 +114,7 @@ CLI input
 ## verification
 
 - For rendering changes: run `bun run typecheck`, `bun test`, `bun run test:integration`, `bun run test:tty-smoke`, and do one real TTY smoke run on an actual diff.
-- For interaction, layout, scrolling, navigation, windowing, or other terminal-native behavior: add or update PTY integration coverage in `test/integration/*.integration.ts` and run it with `bun run test:integration`.
+- For interaction, layout, scrolling, navigation, windowing, or other terminal-native behavior: add or update PTY integration coverage in `test/pty/*-integration.test.ts` and run it with `bun run test:integration`.
 - For CLI, config, or pager work: make sure the relevant source invocation still works (`diff`, `show`, `patch`, or `pager`).
 - Preserve current interaction model unless the user asks to change it explicitly.
 

CONTRIBUTING.md

@@ -91,6 +91,17 @@ bun run publish:prebuilt:npm -- --dry-run
 - CLI, config, or pager changes: verify the relevant source invocation still works, such as `diff`, `show`, `patch`, or `pager`.
 - Packaging or release changes: run the pack and prebuilt checks locally before opening a PR.
 
+## Test layout
+
+- Most unit tests are colocated in `src/` beside the code they cover.
+- `test/helpers/` contains shared test-only fixtures used by those unit tests.
+- `test/cli/` covers black-box CLI behavior.
+- `test/session/` covers daemon, broker, and session-CLI integration flows.
+- `test/pty/` covers PTY-backed live UI integration.
+- `test/smoke/` contains opt-in transcript-based TTY smoke tests.
+
+See [`test/README.md`](test/README.md) for the intent behind each top-level test category.
+
 ## Architecture
 
 ```text

package.json

@@ -49,8 +49,8 @@
     "lint:fix": "oxlint . --fix",
     "prepare": "simple-git-hooks",
     "test": "\"${npm_execpath:-bun}\" test",
-    "test:integration": "\"${npm_execpath:-bun}\" test ./test/integration/tuistory-hunk.integration.ts",
-    "test:tty-smoke": "HUNK_RUN_TTY_SMOKE=1 \"${npm_execpath:-bun}\" test test/tty-render-smoke.test.ts",
+    "test:integration": "\"${npm_execpath:-bun}\" test ./test/pty",
+    "test:tty-smoke": "HUNK_RUN_TTY_SMOKE=1 \"${npm_execpath:-bun}\" test ./test/smoke",
     "check:pack": "bun run ./scripts/check-pack.ts",
     "check:prebuilt-pack": "bun run ./scripts/check-prebuilt-pack.ts",
     "smoke:prebuilt-install": "bun run ./scripts/smoke-prebuilt-install.ts",

test/README.md

@@ -0,0 +1,37 @@
+# Test layout
+
+Most Hunk tests are colocated in `src/` beside the code they cover.
+
+The top-level `test/` tree is reserved for cases that intentionally exercise the product across module, process, repo, or terminal boundaries.
+
+## Structure
+
+```text
+test/
+  helpers/   shared unit-test fixtures
+  cli/       black-box CLI contracts
+  session/   daemon, broker, and session-CLI flows
+  pty/       live PTY-driven UI integration
+  smoke/     thin terminal transcript sanity checks
+```
+
+## What lives here
+
+- `test/helpers/` — shared test-only builders and fixtures reused by colocated unit tests.
+- `test/cli/` — black-box CLI contract tests that spawn the real entrypoint and assert help, version, pager fallback, and friendly error output.
+- `test/session/` — daemon, broker, and session-CLI coverage. These tests often start subprocesses, create temp repos/files, and verify cross-process behavior.
+- `test/pty/` — PTY-backed live UI integration tests for resize, navigation, mouse input, layout changes, and note visibility.
+- `test/smoke/` — opt-in terminal transcript smoke coverage for real TTY rendering (`bun run test:tty-smoke`).
+
+## Why these are not colocated
+
+These tests do not belong to a single source file. They usually verify product-level behavior such as:
+
+- command-line contracts
+- subprocess and daemon lifecycle
+- live session brokering
+- PTY / terminal rendering behavior
+- full review-flow interactions across multiple modules
+
+If a test mainly targets one module or helper, keep it colocated in `src/`.
+If it needs a real repo, subprocess, daemon, PTY, or transcript-level assertion, it likely belongs under `test/`.

test/help-output.test.ts test/cli/entrypoint.test.tstest/help-output.test.ts renamed to test/cli/entrypoint.test.ts

@@ -18,7 +18,7 @@ function git(cwd: string, ...args: string[]) {
   }
 }
 
-describe("CLI help output", () => {
+describe("CLI entrypoint contracts", () => {
   test("bare hunk prints standard help without terminal takeover sequences", () => {
     const proc = Bun.spawnSync(["bun", "run", "src/main.tsx"], {
       cwd: process.cwd(),
@@ -89,7 +89,7 @@ describe("CLI help output", () => {
   });
 
   test("prints the package version for --version without terminal takeover sequences", () => {
-    const expectedVersion = require("../package.json").version;
+    const expectedVersion = require("../../package.json").version;
     const proc = Bun.spawnSync(["bun", "run", "src/main.tsx", "--version"], {
       cwd: process.cwd(),
       stdin: "ignore",

test/integration/tuistoryHarness.ts test/pty/harness.tstest/integration/tuistoryHarness.ts renamed to test/pty/harness.ts

@@ -87,8 +87,8 @@ function runGit(args: string[], cwd: string, allowExitCodeOne = false) {
   return proc.stdout;
 }
 
-/** Build a fresh helper that tracks its own temp directories for one integration test file. */
-export function createTuistoryHarness() {
+/** Build a fresh PTY test helper that tracks its own temp directories for one integration test file. */
+export function createPtyHarness() {
   const tempDirs: string[] = [];
 
   function makeTempDir(prefix: string) {

…integration/tuistory-hunk.integration.ts test/pty/ui-integration.test.tstest/integration/tuistory-hunk.integration.ts renamed to test/pty/ui-integration.test.ts test/integration/tuistory-hunk.integration.ts renamed to test/pty/ui-integration.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, setDefaultTimeout, test } from "bun:test";
-import { createTuistoryHarness } from "./tuistoryHarness";
+import { createPtyHarness } from "./harness";
 
-const harness = createTuistoryHarness();
+const harness = createPtyHarness();
 
 /** Give PTY-backed startup and redraws enough headroom for slower CI machines. */
 setDefaultTimeout(20_000);
@@ -10,7 +10,7 @@ afterEach(() => {
   harness.cleanup();
 });
 
-describe("Hunk integration via tuistory", () => {
+describe("live UI integration", () => {
   test("real PTY sessions can toggle wrapped lines on and off", async () => {
     const fixture = harness.createLongWrapFilePair();
     const session = await harness.launchHunk({

test/mcp-e2e.test.ts test/session/broker-e2e.test.tstest/mcp-e2e.test.ts renamed to test/session/broker-e2e.test.ts

@@ -194,7 +194,7 @@ afterEach(() => {
   cleanupTempDirs();
 });
 
-describe("live session end-to-end", () => {
+describe("session broker end-to-end", () => {
   test("a live Hunk session auto-starts the daemon and renders CLI comments inline", async () => {
     if (!ttyToolsAvailable) {
       return;

test/session-cli.test.ts test/session/cli.test.tstest/session-cli.test.ts renamed to test/session/cli.test.ts

@@ -128,7 +128,7 @@ afterEach(() => {
   cleanupTempDirs();
 });
 
-describe("session CLI", () => {
+describe("session CLI integration", () => {
   test("list/get/context expose live Hunk sessions through the daemon", async () => {
     if (!ttyToolsAvailable) {
       return;

test/mcp-serve-process.test.ts test/session/daemon.test.tstest/mcp-serve-process.test.ts renamed to test/session/daemon.test.ts

@@ -67,7 +67,7 @@ afterEach(async () => {
   );
 });
 
-describe("mcp serve process lifecycle", () => {
+describe("session daemon lifecycle", () => {
   test("exits cleanly after SIGTERM instead of hot-looping after server shutdown", async () => {
     const port = await reserveLoopbackPort();
     const proc = Bun.spawn(["bun", "run", "src/main.tsx", "mcp", "serve"], {