@gallopsystems/agent-skills 1.0.0

package/plugins/nitro-testing/skills/nitro-testing/test-utils.md

@@ -0,0 +1,262 @@
+# Test Utilities
+
+> **Example:** [test-utils-index.ts](./examples/test-utils-index.ts)
+
+Mock event creators, global stubs, and assertion helpers for testing Nitro handlers.
+
+## Mock Event Helpers
+
+Create H3 events for testing handlers:
+
+```typescript
+import { createEvent } from "h3";
+import { IncomingMessage, ServerResponse } from "http";
+import { Socket } from "net";
+
+type Params = Record<string, string | number>;
+
+export function createMockEvent(options: {
+  method?: string;
+  params?: Params;
+  body?: unknown;
+  query?: Record<string, string>;
+}) {
+  const { method = "GET", params = {}, body, query = {} } = options;
+
+  const socket = new Socket();
+  const req = new IncomingMessage(socket);
+  req.method = method;
+  req.url = "/" + (Object.keys(query).length
+    ? "?" + new URLSearchParams(query).toString()
+    : "");
+
+  const res = new ServerResponse(req);
+  const event = createEvent(req, res);
+
+  // Set route params
+  event.context.params = Object.fromEntries(
+    Object.entries(params).map(([k, v]) => [k, String(v)])
+  );
+
+  // Set mock body and query for validation functions
+  if (body !== undefined) {
+    event.context._mockBody = body;
+  }
+  if (Object.keys(query).length > 0) {
+    event.context._mockQuery = query;
+  }
+
+  return event;
+}
+
+// Convenience helpers
+export function mockGet(params: Params, query?: Record<string, string>) {
+  return createMockEvent({ method: "GET", params, query });
+}
+
+export function mockPost(params: Params, body: unknown) {
+  return createMockEvent({ method: "POST", params, body });
+}
+
+export function mockPatch(params: Params, body: unknown) {
+  return createMockEvent({ method: "PATCH", params, body });
+}
+
+export function mockDelete(params: Params) {
+  return createMockEvent({ method: "DELETE", params });
+}
+```
+
+### Usage
+
+```typescript
+// GET /api/users/123?include=profile
+const event = mockGet({ id: 123 }, { include: "profile" });
+
+// POST /api/users with JSON body
+const event = mockPost({}, { email: "test@example.com", name: "Test" });
+
+// PATCH /api/users/123 with partial update
+const event = mockPatch({ id: 123 }, { status: "active" });
+
+// DELETE /api/users/123
+const event = mockDelete({ id: 123 });
+```
+
+## Global Stubs
+
+Stub Nuxt auto-imports so handlers work in test environment:
+
+```typescript
+import { vi } from "vitest";
+
+export async function setupHandlerMocks() {
+  // Unwrap defineEventHandler
+  vi.stubGlobal("defineEventHandler", (handler: Function) => handler);
+
+  // Default test user
+  vi.stubGlobal("getUserSession", async () => ({
+    user: { id: 1, firstName: "Test", lastName: "User", role: "admin" },
+  }));
+
+  vi.stubGlobal("setUserSession", async () => {});
+
+  // Database access (currentTrx set by test fixture)
+  vi.stubGlobal("useDatabase", () => {
+    if (!currentTrx) {
+      throw new Error("useDatabase called outside of test transaction");
+    }
+    return currentTrx;
+  });
+
+  // Error helper
+  vi.stubGlobal("createError", (opts: {
+    statusCode: number;
+    message?: string;
+    statusMessage?: string;
+    data?: unknown;
+  }) => {
+    const error = new Error(opts.message || opts.statusMessage || "") as any;
+    error.statusCode = opts.statusCode;
+    if (opts.data !== undefined) error.data = opts.data;
+    return error;
+  });
+
+  // Route params
+  vi.stubGlobal("getRouterParam", (event: any, param: string) => {
+    return event.context.params?.[param];
+  });
+
+  vi.stubGlobal("getValidatedRouterParams", async (event: any, validate: Function) => {
+    return validate(event.context.params ?? {});
+  });
+
+  // Query params
+  vi.stubGlobal("getQuery", (event: any) => {
+    return event.context._mockQuery ?? {};
+  });
+
+  vi.stubGlobal("getValidatedQuery", async (event: any, validate: Function) => {
+    return validate(event.context._mockQuery ?? {});
+  });
+
+  // Request body
+  vi.stubGlobal("readBody", async (event: any) => event.context._mockBody);
+
+  vi.stubGlobal("readValidatedBody", async (event: any, validate: Function) => {
+    return validate(event.context._mockBody ?? {});
+  });
+}
+```
+
+## Assertion Helpers
+
+### expectHttpError
+
+Test that handlers throw proper HTTP errors:
+
+```typescript
+export async function expectHttpError(
+  promise: Promise<unknown>,
+  expected: { statusCode: number; message?: string }
+) {
+  await expect(promise).rejects.toMatchObject(expected);
+}
+```
+
+### Usage
+
+```typescript
+test("returns 404 for non-existent user", async ({ factories: _ }) => {
+  const event = mockGet({ id: 999999 });
+
+  await expectHttpError(handler(event), {
+    statusCode: 404,
+    message: "User not found",
+  });
+});
+
+test("returns 400 for invalid input", async ({ factories: _ }) => {
+  const event = mockPost({}, { invalidField: "bad" });
+
+  await expectHttpError(handler(event), { statusCode: 400 });
+});
+
+test("returns 401 for unauthenticated request", async ({ factories: _ }) => {
+  // Override default session
+  vi.mocked(getUserSession).mockResolvedValueOnce({ user: null });
+
+  const event = mockGet({});
+  await expectHttpError(handler(event), { statusCode: 401 });
+});
+```
+
+## Customizing Session Per Test
+
+Override the default test user:
+
+```typescript
+import { vi } from "vitest";
+
+test("non-admin cannot delete", async ({ factories }) => {
+  // Override session for this test
+  vi.stubGlobal("getUserSession", async () => ({
+    user: { id: 2, role: "user" },  // Not admin
+  }));
+
+  const item = await factories.item();
+  const event = mockDelete({ id: item.id });
+
+  await expectHttpError(handler(event), { statusCode: 403 });
+});
+```
+
+Or use `vi.mocked` for one-off overrides:
+
+```typescript
+test("user can only see own items", async ({ factories }) => {
+  const owner = await factories.user();
+  const other = await factories.user();
+  const item = await factories.item({ ownerId: owner.id });
+
+  // Mock as the other user
+  vi.mocked(getUserSession).mockResolvedValueOnce({
+    user: { id: other.id, role: "user" },
+  });
+
+  const event = mockGet({ id: item.id });
+  await expectHttpError(handler(event), { statusCode: 404 });
+});
+```
+
+## Re-exports for Convenience
+
+Export everything from one place:
+
+```typescript
+// server/test-utils/index.ts
+export { describe, expect, beforeAll } from "vitest";
+export { test } from "./fixtures";  // Custom fixture
+export {
+  createMockEvent,
+  mockGet,
+  mockPost,
+  mockPatch,
+  mockDelete,
+  expectHttpError,
+} from "./helpers";
+export { setupHandlerMocks } from "./stubs";
+export type { Factories } from "./factories";
+```
+
+Then in tests:
+
+```typescript
+import {
+  describe,
+  test,
+  expect,
+  mockPost,
+  expectHttpError,
+} from "~/server/test-utils";
+```

package/plugins/nitro-testing/skills/nitro-testing/transaction-rollback.md

@@ -0,0 +1,183 @@
+# Transaction Rollback Pattern
+
+> **Example:** [test-utils-index.ts](./examples/test-utils-index.ts)
+
+The core isolation pattern: each test runs inside a database transaction that auto-rolls back.
+
+## Why This Pattern?
+
+| Approach | Speed | Isolation | Real SQL |
+|----------|-------|-----------|----------|
+| Truncate tables | Slow | ✅ | ✅ |
+| Mock database | Fast | ✅ | ❌ |
+| **Transaction rollback** | **Fast** | **✅** | **✅** |
+
+Transaction rollback gives you real SQL testing with mock-like speed.
+
+## Implementation
+
+### Custom Vitest Fixture
+
+```typescript
+import { vi, test as base, expect } from "vitest";
+import { db } from "../utils/db";
+import type { Transaction } from "kysely";
+import type { DB } from "../db/db";
+
+// Current test transaction - handlers access via stubbed useDatabase
+let currentTrx: Transaction<DB> | null = null;
+
+interface TestFixtures {
+  factories: Factories;
+  db: Transaction<DB>;
+}
+
+export const test = base.extend<TestFixtures>({
+  // The factories fixture sets up the transaction
+  factories: async ({}, use) => {
+    await db.transaction().execute(async (trx) => {
+      currentTrx = trx;
+      try {
+        await use(createFactories(trx));
+        // Force rollback by throwing
+        throw { __rollback: true };
+      } finally {
+        currentTrx = null;
+      }
+    }).catch((e) => {
+      // Swallow our rollback signal
+      if (e && typeof e === "object" && "__rollback" in e) {
+        return;
+      }
+      throw e;
+    });
+  },
+
+  // The db fixture exposes the transaction for direct queries
+  db: async ({ factories: _ }, use) => {
+    if (!currentTrx) {
+      throw new Error("db fixture used outside transaction context");
+    }
+    await use(currentTrx);
+  },
+});
+
+export { describe, expect, beforeAll } from "vitest";
+```
+
+### Stubbing useDatabase
+
+```typescript
+// In setup.ts or as part of setupHandlerMocks()
+vi.stubGlobal("useDatabase", () => {
+  if (!currentTrx) {
+    throw new Error("useDatabase called outside of test transaction");
+  }
+  return currentTrx;
+});
+```
+
+Now any handler code that calls `useDatabase()` gets the test transaction.
+
+## Handling Nested Transactions
+
+Real code often uses `db.transaction()` for atomic operations. Since tests already run in a transaction, we need to handle nested transactions:
+
+```typescript
+// Patch Transaction prototype to handle nesting
+const KyselyModule = await import("kysely");
+const TransactionClass = (KyselyModule as any).Transaction;
+
+if (TransactionClass?.prototype) {
+  TransactionClass.prototype.transaction = function () {
+    const self = this;
+    return {
+      execute: async <T>(callback: (trx: any) => Promise<T>): Promise<T> => {
+        // Just run callback with same transaction (no nesting)
+        return callback(self);
+      },
+    };
+  };
+}
+```
+
+This makes code like this work transparently:
+
+```typescript
+// In production: creates real nested transaction
+// In tests: reuses the test transaction
+async function createOrder(data: OrderData) {
+  return db.transaction().execute(async (trx) => {
+    const order = await trx.insertInto("order").values(data)...;
+    await trx.insertInto("order_item").values(...)...;
+    return order;
+  });
+}
+```
+
+## Usage Pattern
+
+```typescript
+import { describe, test, expect, mockPost } from "~/server/test-utils";
+import handler from "./index.post";
+
+describe("POST /api/orders", () => {
+  test("creates order with items", async ({ factories, db }) => {
+    // Create test data using factories (transaction-bound)
+    const user = await factories.user();
+    const product = await factories.product({ price: 100 });
+
+    // Test the handler
+    const event = mockPost({}, {
+      userId: user.id,
+      items: [{ productId: product.id, quantity: 2 }],
+    });
+    const result = await handler(event);
+
+    // Verify in database
+    const order = await db
+      .selectFrom("order")
+      .where("id", "=", result.id)
+      .selectAll()
+      .executeTakeFirst();
+
+    expect(order?.total).toBe(200);
+
+    // Verify order items
+    const items = await db
+      .selectFrom("order_item")
+      .where("order_id", "=", result.id)
+      .selectAll()
+      .execute();
+
+    expect(items).toHaveLength(1);
+  });
+  // Transaction rolls back - database unchanged
+});
+```
+
+## Key Points
+
+1. **Always destructure `factories`** - Even if unused, it triggers transaction setup
+2. **Use `db` fixture for assertions** - Not the real db import
+3. **Nested transactions work** - Thanks to prototype patching
+4. **No cleanup needed** - Rollback happens automatically
+5. **Tests are isolated** - Can't affect each other
+
+## Gotcha: Unused Factories
+
+Even if you don't create test data, you need the fixture to set up the transaction:
+
+```typescript
+// ❌ Wrong - no transaction, useDatabase will fail
+test("returns empty list", async () => {
+  const result = await handler(mockGet({}));
+  expect(result).toEqual([]);
+});
+
+// ✅ Right - transaction set up via factories fixture
+test("returns empty list", async ({ factories: _ }) => {
+  const result = await handler(mockGet({}));
+  expect(result).toEqual([]);
+});
+```

package/plugins/nitro-testing/skills/nitro-testing/vitest-config.md

@@ -0,0 +1,236 @@
+# Vitest Configuration
+
+> **Example:** [vitest.config.ts](./examples/vitest.config.ts)
+
+Configure Vitest for testing Nitro API handlers.
+
+## Basic Configuration
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import path from "path";
+
+export default defineConfig({
+  test: {
+    // Enable globals (describe, test, expect without imports)
+    globals: true,
+
+    // Node environment (not browser)
+    environment: "node",
+
+    // Run once before all tests - reset DB and run migrations
+    globalSetup: ["./server/test-utils/global-setup.ts"],
+
+    // Run before each test file - set up stubs
+    setupFiles: ["./server/test-utils/setup.ts"],
+
+    // Coverage configuration
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "html", "lcov", "json", "json-summary"],
+      include: ["server/**/*.ts"],
+      exclude: [
+        "server/**/*.test.ts",
+        "server/test-utils/**",
+        "server/db/migrations/**",
+        "server/db/db.d.ts",
+      ],
+      reportsDirectory: "./coverage",
+    },
+  },
+
+  resolve: {
+    alias: {
+      "~": path.resolve(__dirname),
+      "@": path.resolve(__dirname),
+    },
+  },
+});
+```
+
+## Global Setup (Runs Once)
+
+```typescript
+// server/test-utils/global-setup.ts
+import { Kysely, PostgresDialect, Migrator, FileMigrationProvider } from "kysely";
+import { Pool } from "pg";
+import path from "path";
+import { promises as fs } from "fs";
+
+function getTestConnectionString(): string {
+  if (process.env.TEST_POSTGRESQL_CONNECTION_STRING) {
+    return process.env.TEST_POSTGRESQL_CONNECTION_STRING;
+  }
+  return "postgresql://localhost/myapp-test";
+}
+
+export async function setup() {
+  const connectionString = getTestConnectionString();
+  const pool = new Pool({ connectionString });
+
+  // Check database exists
+  try {
+    await pool.query("SELECT 1");
+  } catch (err: any) {
+    if (err.code === "3D000") {
+      console.error(`
+╭─────────────────────────────────────────────────────╮
+│  Error: Test database does not exist.               │
+│                                                     │
+│  Run: createdb myapp-test                           │
+╰─────────────────────────────────────────────────────╯
+`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Drop all tables and types for clean slate
+  await pool.query(`
+    DO $$ DECLARE r RECORD;
+    BEGIN
+      FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = 'public') LOOP
+        EXECUTE 'DROP TABLE IF EXISTS ' || quote_ident(r.tablename) || ' CASCADE';
+      END LOOP;
+      FOR r IN (SELECT typname FROM pg_type t
+                JOIN pg_namespace n ON t.typnamespace = n.oid
+                WHERE n.nspname = 'public' AND t.typtype = 'e') LOOP
+        EXECUTE 'DROP TYPE IF EXISTS ' || quote_ident(r.typname) || ' CASCADE';
+      END LOOP;
+    END $$;
+  `);
+  await pool.end();
+
+  // Run migrations
+  const db = new Kysely({
+    dialect: new PostgresDialect({
+      pool: new Pool({ connectionString }),
+    }),
+  });
+
+  const migrator = new Migrator({
+    db,
+    provider: new FileMigrationProvider({
+      fs,
+      path,
+      migrationFolder: path.resolve(__dirname, "../db/migrations"),
+    }),
+  });
+
+  const { error, results } = await migrator.migrateToLatest();
+
+  if (error) {
+    console.error("Migration failed:", error);
+    throw error;
+  }
+
+  const applied = results?.filter((r) => r.status === "Success") ?? [];
+  console.log(`Test DB ready: ${applied.length} migrations applied`);
+
+  await db.destroy();
+}
+```
+
+## Setup File (Runs Per Test File)
+
+```typescript
+// server/test-utils/setup.ts
+import { vi } from "vitest";
+
+// Get test database connection
+function getTestConnectionString(): string {
+  if (process.env.TEST_POSTGRESQL_CONNECTION_STRING) {
+    return process.env.TEST_POSTGRESQL_CONNECTION_STRING;
+  }
+  return "postgresql://localhost/myapp-test";
+}
+
+// Stub useRuntimeConfig before anything else
+vi.stubGlobal("useRuntimeConfig", () => ({
+  postgresql: {
+    connectionString: getTestConnectionString(),
+  },
+  public: {
+    environment: "test",
+  },
+}));
+
+// Set up handler mocks
+const { setupHandlerMocks } = await import("./index");
+await setupHandlerMocks();
+```
+
+## Package.json Scripts
+
+```json
+{
+  "scripts": {
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:run": "vitest run"
+  }
+}
+```
+
+## TypeScript Configuration
+
+```json
+// tsconfig.json - ensure vitest types are included
+{
+  "compilerOptions": {
+    "types": ["vitest/globals"]
+  }
+}
+```
+
+## Test File Pattern
+
+By default, Vitest finds files matching:
+- `**/*.test.ts`
+- `**/*.spec.ts`
+
+Co-locate tests with handlers:
+
+```
+server/
+  api/
+    users/
+      index.get.ts       # Handler
+      index.get.test.ts  # Test
+      index.post.ts
+      index.post.test.ts
+      [id].get.ts
+      [id].get.test.ts
+```
+
+## Environment Variables
+
+```bash
+# Local development
+# Uses postgresql://localhost/myapp-test by default
+
+# CI/CD
+TEST_POSTGRESQL_CONNECTION_STRING=postgresql://postgres:postgres@localhost:5432/myapp-test
+```
+
+## Coverage Thresholds (Optional)
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    coverage: {
+      // Fail if coverage drops below thresholds
+      thresholds: {
+        lines: 80,
+        functions: 80,
+        branches: 70,
+        statements: 80,
+      },
+    },
+  },
+});
+```

package/plugins/nuxt-nitro-api/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "nuxt-nitro-api",
+  "description": "Nuxt 3 / Nitro API patterns: validation, auth, SSR, tasks, SSE",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}