@jterrazz/test 4.0.1 → 5.1.0

package/README.md

@@ -39,7 +39,7 @@ test("creates a user", async () => {
     .run();
 
   // Then — user created
-  result.status.toBe(201);
+  expect(result.status).toBe(201);
   await result.table("users").toMatch({
     columns: ["name"],
     rows: [["Alice"], ["Bob"]],
@@ -69,11 +69,11 @@ test("builds the project", async () => {
   const result = await spec("build").project("sample-app").exec("build").run();
 
   // Then — ESM output with source maps
-  result.exitCode.toBe(0);
-  result.stdout.toContain("Build completed");
-  result.file("dist/index.js").toExist();
-  result.file("dist/index.cjs").not.toExist();
-  result.file("dist/index.js").toContain("Hello");
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("Build completed");
+  expect(result.file("dist/index.js").exists).toBe(true);
+  expect(result.file("dist/index.cjs").exists).toBe(false);
+  expect(result.file("dist/index.js").content).toContain("Hello");
 });
 ```
 
@@ -157,50 +157,69 @@ Every test follows the same pattern: `spec("label") → setup → action → ass
 
 **CLI:**
 
-| Method                                 | Description                                                 |
-| -------------------------------------- | ----------------------------------------------------------- |
-| `.exec("args")`                        | Run command (blocking)                                      |
-| `.exec(["build", "start"])`            | Run commands sequentially in same directory                 |
-| `.spawn("args", { waitFor, timeout })` | Run long-lived process, resolve on pattern match or timeout |
+| Method                                 | Description                                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------------------- |
+| `.exec("args")`                        | Run command (blocking)                                                                |
+| `.exec(["build", "start"])`            | Run commands sequentially in same directory                                           |
+| `.spawn("args", { waitFor, timeout })` | Run long-lived process, resolve on pattern match or timeout                           |
+| `.env({ KEY: "value" })`               | Set env vars on the child process (`null` unsets, `$WORKDIR` expands to the temp cwd) |
 
 ### Assertions
 
-Assertions use a scoped API: `result.{scope}.{assertion}`. Database assertions (`result.table()`) are async.
-
-**HTTP-specific:**
-
-| Method                                     | Description                                        |
-| ------------------------------------------ | -------------------------------------------------- |
-| `result.status.toBe(code)`                 | Assert HTTP status code                            |
-| `result.response.toMatchFile("file.json")` | Assert response body matches `responses/file.json` |
-
-**CLI-specific:**
-
-| Method                                              | Description                                        |
-| --------------------------------------------------- | -------------------------------------------------- |
-| `result.exitCode.toBe(code)`                        | Assert process exit code                           |
-| `result.stdout.toContain(str)`                      | Assert stdout contains string                      |
-| `result.stdout.not.toContain(str)`                  | Assert stdout does not contain string              |
-| `result.stdout.toContain(str, { near: "ctx" })`     | Assert stdout contains string near context         |
-| `result.stderr.toContain(str)`                      | Assert stderr contains string                      |
-| `result.stderr.not.toContain(str)`                  | Assert stderr does not contain string              |
-| `result.stderr.not.toContain(str, { near: "ctx" })` | Assert stderr does not contain string near context |
-| `result.stdout.toMatch(/regex/)`                    | Assert stdout matches regex                        |
-| `result.stdout.toMatchFile("file.txt")`             | Assert stdout matches `expected/file.txt`          |
-| `result.stderr.toMatchFile("file.txt")`             | Assert stderr matches `expected/file.txt`          |
-| `result.stdout.toBeEmpty()`                         | Assert stdout is empty                             |
-
-**Cross-mode:**
-
-| Method                                                             | Description                             |
-| ------------------------------------------------------------------ | --------------------------------------- |
-| `await result.table(name).toMatch({ columns, rows })`              | Assert database table contents          |
-| `await result.table(name, { service }).toMatch({ columns, rows })` | Assert on a specific database           |
-| `await result.table(name).toBeEmpty()`                             | Assert database table is empty          |
-| `result.file(path).toExist()`                                      | Assert file exists in working directory |
-| `result.file(path).not.toExist()`                                  | Assert file does not exist              |
-| `result.file(path).toContain(content)`                             | Assert file contains string             |
-| `result.file(path).toMatch(/regex/)`                               | Assert file content matches regex       |
+Result properties are raw values — use vitest `expect()` for assertions. Database and response file assertions use custom async methods.
+
+**Raw values (vitest expect):**
+
+| Expression                                   | Description                 |
+| -------------------------------------------- | --------------------------- |
+| `expect(result.exitCode).toBe(0)`            | CLI exit code               |
+| `expect(result.status).toBe(201)`            | HTTP status code            |
+| `expect(result.stdout).toContain("hello")`   | CLI stdout contains string  |
+| `expect(result.stderr).not.toContain("err")` | CLI stderr does not contain |
+
+**Files (result.file returns {exists, content}):**
+
+| Expression                                                        | Description                 |
+| ----------------------------------------------------------------- | --------------------------- |
+| `expect(result.file("dist/index.js").exists).toBe(true)`          | Assert file exists          |
+| `expect(result.file("dist/index.js").content).toContain("Hello")` | Assert file contains string |
+| `expect(result.file("dist/index.cjs").exists).toBe(false)`        | Assert file does not exist  |
+
+**Directories (CLI scaffolding / codegen output):**
+
+| Expression                                                        | Description                                                                    |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `await result.directory("out").toMatchFixture("go-api")`          | Snapshot the tree against `expected/go-api/`, structured diff on mismatch      |
+| `await result.directory().toMatchFixture("scaffold", { ignore })` | Pass extra ignore patterns; defaults already skip `.git`, `node_modules`, etc. |
+| `await result.directory("out").files()`                           | List all files (recursive, sorted) for ad-hoc assertions                       |
+
+Run with `JTERRAZZ_TEST_UPDATE=1` (or vitest `-u`) to overwrite fixtures with the current output. Fixtures live at `{test}/expected/{name}/` — same convention as `responses/` for HTTP bodies.
+
+**Grep (scoped text matching):**
+
+```typescript
+import { grep } from "@jterrazz/test";
+
+expect(grep(result.stdout, "unused-var.ts")).toContain("no-unused-vars");
+expect(grep(result.stdout, "valid/sorted.ts")).not.toContain("sort-imports");
+```
+
+`grep(output, pattern)` filters multi-line output to the block matching `pattern`, returning a string for vitest assertions.
+
+**Response (HTTP body):**
+
+| Expression                                      | Description                                                                 |
+| ----------------------------------------------- | --------------------------------------------------------------------------- |
+| `result.response.toMatchFile("expected.json")`  | Custom — compares body to `responses/expected.json`, shows diff on mismatch |
+| `expect(result.response.body).toEqual({ ... })` | Raw body object for vitest assertions                                       |
+
+**Tables (custom async — database queries):**
+
+| Expression                                                                      | Description                    |
+| ------------------------------------------------------------------------------- | ------------------------------ |
+| `await result.table("users").toMatch({ columns: ["name"], rows: [["Alice"]] })` | Assert database table contents |
+| `await result.table("events", { service: "analytics-db" }).toMatch({ ... })`    | Assert on a specific database  |
+| `await result.table("users").toBeEmpty()`                                       | Assert database table is empty |
 
 ## Multi-database support
 
@@ -221,6 +240,7 @@ const result = await spec("cross-db")
   .post("/users", "request.json")
   .run();
 
+expect(result.status).toBe(201);
 await result.table("users").toMatch({ columns: ["name"], rows: [["Alice"]] });
 await result.table("events", { service: "analytics-db" }).toMatch({
   columns: ["type"],
@@ -306,7 +326,7 @@ test("creates a user and returns 201", async () => {
     .run();
 
   // Then — user created with all three in table
-  result.status.toBe(201);
+  expect(result.status).toBe(201);
   await result.table("users").toMatch({
     columns: ["name"],
     rows: [["Alice"], ["Bob"], ["Charlie"]],