devstack 0.1.0

package/vendor/skills/skills/vitest/references/core-hooks.md

@@ -0,0 +1,245 @@
+---
+name: lifecycle-hooks
+description: beforeEach, afterEach, beforeAll, afterAll, and around hooks
+---
+
+# Lifecycle Hooks
+
+## Basic Hooks
+
+```ts
+import { afterAll, afterEach, beforeAll, beforeEach, test } from "vitest";
+
+beforeAll(async () => {
+  // Runs once before all tests in file/suite
+  await setupDatabase();
+});
+
+afterAll(async () => {
+  // Runs once after all tests in file/suite
+  await teardownDatabase();
+});
+
+beforeEach(async () => {
+  // Runs before each test
+  await clearTestData();
+});
+
+afterEach(async () => {
+  // Runs after each test
+  await cleanupMocks();
+});
+```
+
+## Cleanup Return Pattern
+
+Return cleanup function from `before*` hooks:
+
+```ts
+beforeAll(async () => {
+  const server = await startServer();
+
+  // Returned function runs as afterAll
+  return async () => {
+    await server.close();
+  };
+});
+
+beforeEach(async () => {
+  const connection = await connect();
+
+  // Runs as afterEach
+  return () => connection.close();
+});
+```
+
+## Scoped Hooks
+
+Hooks apply to current suite and nested suites:
+
+```ts
+describe("outer", () => {
+  beforeEach(() => console.log("outer before"));
+
+  test("test 1", () => {}); // outer before → test
+
+  describe("inner", () => {
+    beforeEach(() => console.log("inner before"));
+
+    test("test 2", () => {}); // outer before → inner before → test
+  });
+});
+```
+
+## Hook Timeout
+
+```ts
+beforeAll(async () => {
+  await slowSetup();
+}, 30_000); // 30 second timeout
+```
+
+## Around Hooks
+
+Wrap tests with setup/teardown context:
+
+```ts
+import { aroundEach, test } from "vitest";
+
+// Wrap each test in database transaction
+aroundEach(async runTest => {
+  await db.beginTransaction();
+  await runTest(); // Must be called!
+  await db.rollback();
+});
+
+test("insert user", async () => {
+  await db.insert({ name: "Alice" });
+  // Automatically rolled back after test
+});
+```
+
+### aroundAll
+
+Wrap entire suite:
+
+```ts
+import { aroundAll, test } from "vitest";
+
+aroundAll(async runSuite => {
+  console.log("before all tests");
+  await runSuite(); // Must be called!
+  console.log("after all tests");
+});
+```
+
+### Multiple Around Hooks
+
+Nested like onion layers:
+
+```ts
+aroundEach(async runTest => {
+  console.log("outer before");
+  await runTest();
+  console.log("outer after");
+});
+
+aroundEach(async runTest => {
+  console.log("inner before");
+  await runTest();
+  console.log("inner after");
+});
+
+// Order: outer before → inner before → test → inner after → outer after
+```
+
+## Test Hooks
+
+Inside test body:
+
+```ts
+import { onTestFailed, onTestFinished, test } from "vitest";
+
+test("with cleanup", () => {
+  const db = connect();
+
+  // Runs after test finishes (pass or fail)
+  onTestFinished(() => db.close());
+
+  // Only runs if test fails
+  onTestFailed(({ task }) => {
+    console.log("Failed:", task.result?.errors);
+  });
+
+  db.query("SELECT * FROM users");
+});
+```
+
+### Reusable Cleanup Pattern
+
+```ts
+function useTestDb() {
+  const db = connect();
+  onTestFinished(() => db.close());
+  return db;
+}
+
+test("query users", () => {
+  const db = useTestDb();
+  expect(db.query("SELECT * FROM users")).toBeDefined();
+});
+
+test("query orders", () => {
+  const db = useTestDb(); // Fresh connection, auto-closed
+  expect(db.query("SELECT * FROM orders")).toBeDefined();
+});
+```
+
+## Concurrent Test Hooks
+
+For concurrent tests, use context's hooks:
+
+```ts
+test.concurrent("concurrent", ({ onTestFinished }) => {
+  const resource = allocate();
+  onTestFinished(() => resource.release());
+});
+```
+
+## Extended Test Hooks
+
+With `test.extend`, hooks are type-aware:
+
+```ts
+const test = base.extend<{ db: Database }>({
+  db: async ({}, use) => {
+    const db = await createDb();
+    await use(db);
+    await db.close();
+  },
+});
+
+// These hooks know about `db` fixture
+test.beforeEach(({ db }) => {
+  db.seed();
+});
+
+test.afterEach(({ db }) => {
+  db.clear();
+});
+```
+
+## Hook Execution Order
+
+Default order (stack):
+
+1. `beforeAll` (in order)
+2. `beforeEach` (in order)
+3. Test
+4. `afterEach` (reverse order)
+5. `afterAll` (reverse order)
+
+Configure with `sequence.hooks`:
+
+```ts
+defineConfig({
+  test: {
+    sequence: {
+      hooks: "list", // 'stack' (default), 'list', 'parallel'
+    },
+  },
+});
+```
+
+## Key Points
+
+- Hooks are not called during type checking
+- Return cleanup function from `before*` to avoid `after*` duplication
+- `aroundEach`/`aroundAll` must call `runTest()`/`runSuite()`
+- `onTestFinished` always runs, even if test fails
+- Use context hooks for concurrent tests
+
+<!--
+Source references:
+- https://vitest.dev/api/hooks.html
+-->

package/vendor/skills/skills/vitest/references/core-test-api.md

@@ -0,0 +1,237 @@
+---
+name: test-api
+description: test/it function for defining tests with modifiers
+---
+
+# Test API
+
+## Basic Test
+
+```ts
+import { expect, test } from "vitest";
+
+test("adds numbers", () => {
+  expect(1 + 1).toBe(2);
+});
+
+// Alias: it
+import { it } from "vitest";
+
+it("works the same", () => {
+  expect(true).toBe(true);
+});
+```
+
+## Async Tests
+
+```ts
+test("async test", async () => {
+  const result = await fetchData();
+  expect(result).toBeDefined();
+});
+
+// Promises are automatically awaited
+test("returns promise", () => {
+  return fetchData().then(result => {
+    expect(result).toBeDefined();
+  });
+});
+```
+
+## Test Options
+
+```ts
+// Timeout (default: 5000ms)
+test("slow test", async () => {
+  // ...
+}, 10_000);
+
+// Or with options object
+test("with options", { timeout: 10_000, retry: 2 }, async () => {
+  // ...
+});
+```
+
+## Test Modifiers
+
+### Skip Tests
+
+```ts
+test.skip("skipped test", () => {
+  // Won't run
+});
+
+// Conditional skip
+test.skipIf(process.env.CI)("not in CI", () => {});
+test.runIf(process.env.CI)("only in CI", () => {});
+
+// Dynamic skip via context
+test("dynamic skip", ({ skip }) => {
+  skip(someCondition, "reason");
+  // ...
+});
+```
+
+### Focus Tests
+
+```ts
+test.only("only this runs", () => {
+  // Other tests in file are skipped
+});
+```
+
+### Todo Tests
+
+```ts
+test.todo("implement later");
+
+test.todo("with body", () => {
+  // Not run, shows in report
+});
+```
+
+### Failing Tests
+
+```ts
+test.fails("expected to fail", () => {
+  expect(1).toBe(2); // Test passes because assertion fails
+});
+```
+
+### Concurrent Tests
+
+```ts
+// Run tests in parallel
+test.concurrent("test 1", async ({ expect }) => {
+  // Use context.expect for concurrent tests
+  expect(await fetch1()).toBe("result");
+});
+
+test.concurrent("test 2", async ({ expect }) => {
+  expect(await fetch2()).toBe("result");
+});
+```
+
+### Sequential Tests
+
+```ts
+// Force sequential in concurrent context
+test.sequential("must run alone", async () => {});
+```
+
+## Parameterized Tests
+
+### test.each
+
+```ts
+test.each([
+  [1, 1, 2],
+  [1, 2, 3],
+  [2, 1, 3],
+])("add(%i, %i) = %i", (a, b, expected) => {
+  expect(a + b).toBe(expected);
+});
+
+// With objects
+test.each([
+  { a: 1, b: 1, expected: 2 },
+  { a: 1, b: 2, expected: 3 },
+])("add($a, $b) = $expected", ({ a, b, expected }) => {
+  expect(a + b).toBe(expected);
+});
+
+// Template literal
+test.each`
+  a    | b    | expected
+  ${1} | ${1} | ${2}
+  ${1} | ${2} | ${3}
+`("add($a, $b) = $expected", ({ a, b, expected }) => {
+  expect(a + b).toBe(expected);
+});
+```
+
+### test.for
+
+Preferred over `.each` - doesn't spread arrays:
+
+```ts
+test.for([
+  [1, 1, 2],
+  [1, 2, 3],
+])("add(%i, %i) = %i", ([a, b, expected], { expect }) => {
+  // Second arg is TestContext
+  expect(a + b).toBe(expected);
+});
+```
+
+## Test Context
+
+First argument provides context utilities:
+
+```ts
+test("with context", ({ expect, skip, task }) => {
+  console.log(task.name); // Test name
+  skip(someCondition); // Skip dynamically
+  expect(1).toBe(1); // Context-bound expect
+});
+```
+
+## Custom Test with Fixtures
+
+```ts
+import { test as base } from "vitest";
+
+const test = base.extend({
+  db: async ({}, use) => {
+    const db = await createDb();
+    await use(db);
+    await db.close();
+  },
+});
+
+test("query", async ({ db }) => {
+  const users = await db.query("SELECT * FROM users");
+  expect(users).toBeDefined();
+});
+```
+
+## Retry Configuration
+
+```ts
+test("flaky test", { retry: 3 }, async () => {
+  // Retries up to 3 times on failure
+});
+
+// Advanced retry options
+test(
+  "with delay",
+  {
+    retry: {
+      count: 3,
+      delay: 1000,
+      condition: /timeout/i, // Only retry on timeout errors
+    },
+  },
+  async () => {}
+);
+```
+
+## Tags
+
+```ts
+test("database test", { tags: ["db", "slow"] }, async () => {});
+
+// Run with: vitest --tags db
+```
+
+## Key Points
+
+- Tests with no body are marked as `todo`
+- `test.only` throws in CI unless `allowOnly: true`
+- Use context's `expect` for concurrent tests and snapshots
+- Function name is used as test name if passed as first arg
+
+<!--
+Source references:
+- https://vitest.dev/api/test.html
+-->

package/vendor/skills/skills/vitest/references/features-concurrency.md

@@ -0,0 +1,250 @@
+---
+name: concurrency-parallelism
+description: Concurrent tests, parallel execution, and sharding
+---
+
+# Concurrency & Parallelism
+
+## File Parallelism
+
+By default, Vitest runs test files in parallel across workers:
+
+```ts
+defineConfig({
+  test: {
+    // Run files in parallel (default: true)
+    fileParallelism: true,
+
+    // Number of worker threads
+    maxWorkers: 4,
+    minWorkers: 1,
+
+    // Pool type: 'threads', 'forks', 'vmThreads'
+    pool: "threads",
+  },
+});
+```
+
+## Concurrent Tests
+
+Run tests within a file in parallel:
+
+```ts
+// Individual concurrent tests
+test.concurrent("test 1", async ({ expect }) => {
+  expect(await fetch1()).toBe("result");
+});
+
+test.concurrent("test 2", async ({ expect }) => {
+  expect(await fetch2()).toBe("result");
+});
+
+// All tests in suite concurrent
+describe.concurrent("parallel suite", () => {
+  test("test 1", async ({ expect }) => {});
+  test("test 2", async ({ expect }) => {});
+});
+```
+
+**Important:** Use `{ expect }` from context for concurrent tests.
+
+## Sequential in Concurrent Context
+
+Force sequential execution:
+
+```ts
+describe.concurrent("mostly parallel", () => {
+  test("parallel 1", async () => {});
+  test("parallel 2", async () => {});
+
+  test.sequential("must run alone 1", async () => {});
+  test.sequential("must run alone 2", async () => {});
+});
+
+// Or entire suite
+describe.sequential("sequential suite", () => {
+  test("first", () => {});
+  test("second", () => {});
+});
+```
+
+## Max Concurrency
+
+Limit concurrent tests:
+
+```ts
+defineConfig({
+  test: {
+    maxConcurrency: 5, // Max concurrent tests per file
+  },
+});
+```
+
+## Isolation
+
+Each file runs in isolated environment by default:
+
+```ts
+defineConfig({
+  test: {
+    // Disable isolation for faster runs (less safe)
+    isolate: false,
+  },
+});
+```
+
+## Sharding
+
+Split tests across machines:
+
+```bash
+# Machine 1
+vitest run --shard=1/3
+
+# Machine 2
+vitest run --shard=2/3
+
+# Machine 3
+vitest run --shard=3/3
+```
+
+### CI Example (GitHub Actions)
+
+```yaml
+jobs:
+  test:
+    strategy:
+      matrix:
+        shard: [1, 2, 3]
+    steps:
+      - run: vitest run --shard=${{ matrix.shard }}/3 --reporter=blob
+
+  merge:
+    needs: test
+    steps:
+      - run: vitest --merge-reports --reporter=junit
+```
+
+### Merge Reports
+
+```bash
+# Each shard outputs blob
+vitest run --shard=1/3 --reporter=blob --coverage
+vitest run --shard=2/3 --reporter=blob --coverage
+
+# Merge all blobs
+vitest --merge-reports --reporter=json --coverage
+```
+
+## Test Sequence
+
+Control test order:
+
+```ts
+defineConfig({
+  test: {
+    sequence: {
+      // Run tests in random order
+      shuffle: true,
+
+      // Seed for reproducible shuffle
+      seed: 12345,
+
+      // Hook execution order
+      hooks: "stack", // 'stack', 'list', 'parallel'
+
+      // All tests concurrent by default
+      concurrent: true,
+    },
+  },
+});
+```
+
+## Shuffle Tests
+
+Randomize to catch hidden dependencies:
+
+```ts
+// Via CLI
+vitest --sequence.shuffle
+
+// Per suite
+describe.shuffle('random order', () => {
+  test('test 1', () => {})
+  test('test 2', () => {})
+  test('test 3', () => {})
+})
+```
+
+## Pool Options
+
+### Threads (Default)
+
+```ts
+defineConfig({
+  test: {
+    pool: "threads",
+    poolOptions: {
+      threads: {
+        maxThreads: 8,
+        minThreads: 2,
+        isolate: true,
+      },
+    },
+  },
+});
+```
+
+### Forks
+
+Better isolation, slower:
+
+```ts
+defineConfig({
+  test: {
+    pool: "forks",
+    poolOptions: {
+      forks: {
+        maxForks: 4,
+        isolate: true,
+      },
+    },
+  },
+});
+```
+
+### VM Threads
+
+Full VM isolation per file:
+
+```ts
+defineConfig({
+  test: {
+    pool: "vmThreads",
+  },
+});
+```
+
+## Bail on Failure
+
+Stop after first failure:
+
+```bash
+vitest --bail 1    # Stop after 1 failure
+vitest --bail      # Stop on first failure (same as --bail 1)
+```
+
+## Key Points
+
+- Files run in parallel by default
+- Use `.concurrent` for parallel tests within file
+- Always use context's `expect` in concurrent tests
+- Sharding splits tests across CI machines
+- Use `--merge-reports` to combine sharded results
+- Shuffle tests to find hidden dependencies
+
+<!--
+Source references:
+- https://vitest.dev/guide/features.html#running-tests-concurrently
+- https://vitest.dev/guide/improving-performance.html
+-->