@gallopsystems/agent-skills 1.0.0

package/plugins/nitro-testing/skills/nitro-testing/async-testing.md

@@ -0,0 +1,270 @@
+# Async & Automation Testing
+
+> **Example:** [test-utils-index.ts](./examples/test-utils-index.ts)
+
+Test Nitro tasks, background jobs, and automation systems that trigger asynchronously.
+
+## The Challenge
+
+When handlers trigger background tasks, tests need to:
+1. Capture task handlers defined with `defineTask`
+2. Execute tasks when `runTask` is called
+3. Wait for all async operations to complete
+
+## Task Handler Registry
+
+Capture task handlers at registration time:
+
+```typescript
+// Track registered task handlers
+const taskHandlers: Map<string, (opts: { payload: any }) => Promise<any>> = new Map();
+
+// Track pending task executions
+let pendingTasks: Promise<any>[] = [];
+
+// Stub defineTask to capture handlers
+vi.stubGlobal("defineTask", (config: {
+  meta: { name: string };
+  run: (opts: { payload: any }) => Promise<any>;
+}) => {
+  taskHandlers.set(config.meta.name, config.run);
+  return config;
+});
+
+// Stub runTask to execute and track
+vi.stubGlobal("runTask", (taskName: string, options: { payload: any }) => {
+  const handler = taskHandlers.get(taskName);
+  if (!handler) {
+    return Promise.reject(new Error(`Task handler not found: ${taskName}`));
+  }
+  const promise = handler(options);
+  pendingTasks.push(promise);
+  return promise;
+});
+```
+
+## Waiting for Async Operations
+
+```typescript
+/**
+ * Wait for all pending task executions to complete.
+ * Loops because tasks can spawn other tasks.
+ */
+export async function waitForAutomations(): Promise<void> {
+  while (pendingTasks.length > 0) {
+    const tasksToWait = [...pendingTasks];
+    pendingTasks = [];
+    await Promise.allSettled(tasksToWait);
+  }
+}
+```
+
+## Enabling Real Implementations
+
+By default, stub async triggers as no-ops. Tests opt-in to real behavior:
+
+```typescript
+// Default: no-op stub
+vi.stubGlobal("triggerAutomation", () => {});
+
+/**
+ * Enable automation triggers for tests that need them.
+ */
+export async function enableAutomationTriggers() {
+  // Import the task handler to register it
+  await import("../tasks/execute-automation");
+
+  // Import the real trigger function
+  const { triggerAutomation: realTrigger } = await import("../utils/automation");
+
+  // Wrap to track promises
+  vi.stubGlobal("triggerAutomation", (...args: Parameters<typeof realTrigger>) => {
+    const promise = realTrigger(...args);
+    pendingTasks.push(promise);
+    return promise;
+  });
+}
+```
+
+## Usage in Tests
+
+### Basic Automation Test
+
+```typescript
+import {
+  describe,
+  test,
+  expect,
+  mockPost,
+  enableAutomationTriggers,
+  waitForAutomations,
+  beforeAll,
+} from "~/server/test-utils";
+import handler from "./index.post";
+
+// Enable real automations for this file
+beforeAll(async () => {
+  await enableAutomationTriggers();
+});
+
+describe("Job Creation Automations", () => {
+  test("automation creates task when job is created", async ({ factories, db }) => {
+    // Set up automation rule
+    const template = await factories.jobTemplate();
+    await factories.automation({
+      jobTemplateId: template.id,
+      triggerConfig: { subject: "job", event: "created" },
+      actionPayload: { task_type: "Review" },
+    });
+
+    // Create job (triggers automation)
+    const project = await factories.project();
+    const event = mockPost({}, {
+      projectId: project.id,
+      jobTemplateId: template.id,
+      jobType: "Test",
+    });
+    const result = await handler(event);
+
+    // Wait for automation to complete
+    await waitForAutomations();
+
+    // Verify automation created the task
+    const tasks = await db
+      .selectFrom("task")
+      .where("job_id", "=", result.job.id)
+      .selectAll()
+      .execute();
+
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0].task_type).toBe("Review");
+  });
+});
+```
+
+### Chained Automations
+
+```typescript
+test("completing task triggers follow-up automation", async ({ factories, db }) => {
+  const template = await factories.jobTemplate();
+
+  // Automation: when any task completes, create follow-up
+  await factories.automation({
+    jobTemplateId: template.id,
+    triggerConfig: { subject: "task", event: "completed" },
+    actionPayload: { task_type: "Follow-up" },
+  });
+
+  // Create job with initial task
+  const project = await factories.project();
+  const job = await factories.job({ projectId: project.id, jobTemplateId: template.id });
+  const task = await factories.task({ jobId: job.id, status: "Active" });
+
+  // Complete the task
+  const event = mockPatch({}, {
+    tasks: [{ id: task.id, status: "Completed" }],
+  });
+  await taskPatchHandler(event);
+  await waitForAutomations();
+
+  // Should have 2 tasks: original + follow-up
+  const tasks = await db
+    .selectFrom("task")
+    .where("job_id", "=", job.id)
+    .selectAll()
+    .execute();
+
+  expect(tasks).toHaveLength(2);
+  expect(tasks.some(t => t.task_type === "Follow-up")).toBe(true);
+});
+```
+
+### Testing Multiple Async Triggers
+
+```typescript
+test("bulk update triggers multiple automations", async ({ factories, db }) => {
+  const template = await factories.jobTemplate();
+  await factories.automation({
+    jobTemplateId: template.id,
+    triggerConfig: { subject: "task", event: "completed" },
+    actionPayload: { task_type: "Follow-up" },
+  });
+
+  const job = await factories.job({ jobTemplateId: template.id });
+  const tasks = await Promise.all([
+    factories.task({ jobId: job.id, status: "Active" }),
+    factories.task({ jobId: job.id, status: "Active" }),
+    factories.task({ jobId: job.id, status: "Active" }),
+  ]);
+
+  // Complete all 3 tasks in one patch
+  const event = mockPatch({}, {
+    tasks: tasks.map(t => ({ id: t.id, status: "Completed" })),
+  });
+  await handler(event);
+  await waitForAutomations();
+
+  // Should have 6 tasks: 3 original + 3 follow-ups
+  const allTasks = await db
+    .selectFrom("task")
+    .where("job_id", "=", job.id)
+    .selectAll()
+    .execute();
+
+  expect(allTasks).toHaveLength(6);
+  expect(allTasks.filter(t => t.task_type === "Follow-up")).toHaveLength(3);
+});
+```
+
+## Testing Without Automations
+
+Most tests don't need real automations - the stub is a no-op:
+
+```typescript
+// No beforeAll(enableAutomationTriggers) - uses stub
+describe("Basic CRUD", () => {
+  test("creates job without triggering automations", async ({ factories }) => {
+    const project = await factories.project();
+    const event = mockPost({}, { projectId: project.id, jobType: "Test" });
+
+    const result = await handler(event);
+
+    expect(result.job.id).toBeDefined();
+    // No automations ran - triggerAutomation is a no-op
+  });
+});
+```
+
+## Verifying Execution Records
+
+If your system logs automation executions:
+
+```typescript
+test("records automation execution", async ({ factories, db }) => {
+  const template = await factories.jobTemplate();
+  await factories.automation({
+    jobTemplateId: template.id,
+    triggerConfig: { subject: "job", event: "created" },
+  });
+
+  const job = await factories.job({ jobTemplateId: template.id });
+  await waitForAutomations();
+
+  const execution = await db
+    .selectFrom("automation_execution")
+    .where("job_id", "=", job.id)
+    .selectAll()
+    .executeTakeFirst();
+
+  expect(execution?.status).toBe("completed");
+  expect(execution?.affected_entities).toBeDefined();
+});
+```
+
+## Key Patterns
+
+1. **Opt-in real behavior** - Default to stubs, `enableAutomationTriggers()` for tests that need it
+2. **Track all promises** - Both the trigger and the tasks it spawns
+3. **Wait in a loop** - Tasks can spawn more tasks
+4. **Use `Promise.allSettled`** - Don't fail fast, let all settle
+5. **Verify final state** - Check database after `waitForAutomations()`

package/plugins/nitro-testing/skills/nitro-testing/ci-setup.md

@@ -0,0 +1,226 @@
+# CI/CD Setup
+
+Configure GitHub Actions to run tests with a real PostgreSQL database.
+
+## GitHub Actions Workflow
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: myapp-test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "yarn"
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Run tests
+        run: yarn test --coverage
+        env:
+          TEST_POSTGRESQL_CONNECTION_STRING: postgresql://postgres:postgres@localhost:5432/myapp-test
+
+      - name: Upload coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage/
+          retention-days: 7
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "yarn"
+      - run: yarn install --frozen-lockfile
+      - run: yarn typecheck
+```
+
+## Coverage Report on PRs
+
+Add coverage reporting to pull requests:
+
+```yaml
+# .github/workflows/ci.yml (add to test job steps)
+      - name: Coverage Report
+        if: github.event_name == 'pull_request'
+        uses: davelosert/vitest-coverage-report-action@v2
+        with:
+          vite-config-path: vitest.config.ts
+          json-summary-path: coverage/coverage-summary.json
+          json-final-path: coverage/coverage-final.json
+```
+
+## Key Configuration Points
+
+### PostgreSQL Service
+
+```yaml
+services:
+  postgres:
+    image: postgres:15  # Match your production version
+    env:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: myapp-test  # Test database name
+    ports:
+      - 5432:5432
+    options: >-
+      --health-cmd pg_isready
+      --health-interval 10s
+      --health-timeout 5s
+      --health-retries 5
+```
+
+The health check ensures PostgreSQL is ready before tests run.
+
+### Connection String
+
+```yaml
+env:
+  TEST_POSTGRESQL_CONNECTION_STRING: postgresql://postgres:postgres@localhost:5432/myapp-test
+```
+
+This environment variable is read by `global-setup.ts` and `setup.ts`.
+
+### Node.js Version
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: "22"  # Match your project
+    cache: "yarn"       # or "npm"
+```
+
+## Parallel Test Jobs
+
+For faster CI, run tests in parallel (if you have many):
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shard: [1, 2, 3, 4]
+
+    services:
+      postgres:
+        # ... same config
+
+    steps:
+      # ... setup steps
+
+      - name: Run tests (shard ${{ matrix.shard }})
+        run: yarn test --shard=${{ matrix.shard }}/${{ strategy.job-total }}
+        env:
+          TEST_POSTGRESQL_CONNECTION_STRING: postgresql://postgres:postgres@localhost:5432/myapp-test
+```
+
+## Caching Dependencies
+
+The `cache: "yarn"` option caches `node_modules` based on `yarn.lock`:
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: "22"
+    cache: "yarn"  # Automatically caches based on yarn.lock
+```
+
+For npm:
+```yaml
+    cache: "npm"  # Caches based on package-lock.json
+```
+
+## Branch Protection
+
+Configure branch protection rules in GitHub:
+
+1. Go to **Settings → Branches → Add rule**
+2. Branch name pattern: `main`
+3. Enable:
+   - ✅ Require status checks to pass before merging
+   - ✅ Require branches to be up to date before merging
+4. Add required status checks:
+   - `test`
+   - `typecheck`
+
+## Local CI Simulation
+
+Test the CI workflow locally using [act](https://github.com/nektos/act):
+
+```bash
+# Install act
+brew install act
+
+# Run workflow
+act push
+```
+
+Or use Docker directly:
+
+```bash
+# Start test database
+docker run -d --name test-db \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB=myapp-test \
+  -p 5432:5432 \
+  postgres:15
+
+# Run tests
+TEST_POSTGRESQL_CONNECTION_STRING=postgresql://postgres:postgres@localhost:5432/myapp-test \
+  yarn test
+
+# Cleanup
+docker stop test-db && docker rm test-db
+```
+
+## Secrets and Environment Variables
+
+For production-like test databases or external services:
+
+```yaml
+steps:
+  - name: Run tests
+    run: yarn test
+    env:
+      TEST_POSTGRESQL_CONNECTION_STRING: ${{ secrets.TEST_DATABASE_URL }}
+      STRIPE_TEST_KEY: ${{ secrets.STRIPE_TEST_KEY }}
+```
+
+Store secrets in **Settings → Secrets and variables → Actions**.

package/plugins/nitro-testing/skills/nitro-testing/examples/global-setup.ts

@@ -0,0 +1,90 @@
+/**
+ * Vitest Global Setup
+ *
+ * Runs ONCE before all tests to reset and migrate the test database.
+ */
+
+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: unknown) {
+    const pgError = err as { code?: string };
+    if (pgError.code === "3D000") {
+      console.error(`
+╭─────────────────────────────────────────────────────╮
+│  Error: Test database does not exist.               │
+│                                                     │
+│  Run: createdb myapp-test                           │
+│                                                     │
+│  Then re-run your tests.                            │
+╰─────────────────────────────────────────────────────╯
+`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Drop all tables and custom types for clean slate
+  await pool.query(`
+    DO $$ DECLARE
+      r RECORD;
+    BEGIN
+      -- Drop all tables
+      FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = 'public') LOOP
+        EXECUTE 'DROP TABLE IF EXISTS ' || quote_ident(r.tablename) || ' CASCADE';
+      END LOOP;
+      -- Drop all custom enum types
+      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 from scratch
+  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();
+}