Agent skill

testing

Shared database testing patterns with testcontainers and Vitest. Use when writing backend tests, setting up test files, debugging test failures, or configuring Vitest. Triggers on "write tests", "test setup", "testcontainers", "vitest config", "test isolation", or when creating new test suites.

View SKILL.md on GitHub Repository
Stars 27
Forks 4

Install this agent skill to your Project

npx add-skill https://github.com/frmlabz/frm-stack/tree/main/capabilities/backend/skills/testing

SKILL.md

Testing

This repo uses a shared PostgreSQL container with TRUNCATE resets for fast, isolated tests.

Quick Start

typescript
import { describe, it, expect, beforeAll, beforeEach } from "vitest";
import type { Kysely } from "kysely";
import type { DB as DatabaseSchema } from "#schema";
import { getSharedDatabaseHelper, resetSharedDatabase, createTestUser } from "#test-helpers";

describe("My Test Suite", () => {
  let db: Kysely<DatabaseSchema>;

  beforeAll(async () => {
    const dbHelper = await getSharedDatabaseHelper();
    db = dbHelper.db;
  });

  beforeEach(async () => {
    await resetSharedDatabase();
  });

  it("should work", async () => {
    const user = await createTestUser(db);
    expect(user).toBeDefined();
  });
});

Key Functions

Function Purpose
getSharedDatabaseHelper() Get DB connection (call in beforeAll)
resetSharedDatabase() Reset to clean state (call in beforeEach)
createTestUser(db) Create test user fixture

Vitest Config Requirements

typescript
// vitest.config.ts
export default defineConfig({
  test: {
    pool: "threads",      // REQUIRED: threads, not forks
    maxConcurrency: 4,    // Limit parallel tests
    isolate: false,       // Reuse context for speed
    hookTimeout: 120000,  // 2 min for container startup
    testTimeout: 30000,   // 30 sec per test
  }
});

Use createSharedTestConfig() from @yourcompany/backend-core/vitest.config.shared:

typescript
import { mergeConfig, defineConfig } from "vitest/config";
import { createSharedTestConfig } from "@yourcompany/backend-core/vitest.config.shared";

export default mergeConfig(
  createSharedTestConfig({ setupFiles: ["./src/test-setup.ts"] }),
  defineConfig({ /* overrides */ })
);

Common Patterns

Shared Test Data

typescript
let testUser: User;

beforeEach(async () => {
  await resetSharedDatabase();
  testUser = await createTestUser(db); // Create AFTER reset
});

Nested Describes

typescript
describe("Feature", () => {
  beforeEach(async () => {
    await resetSharedDatabase(); // Applies to ALL nested tests
  });

  describe("sub-feature", () => {
    it("test 1", () => { /* clean DB */ });
    it("test 2", () => { /* clean DB */ });
  });
});

Troubleshooting

Issue Cause Solution
"Database not initialized" Test ran before setup Add beforeAll with getSharedDatabaseHelper()
Tests interfering Missing reset Add resetSharedDatabase() in beforeEach
Connection refused Timeout too short Increase hookTimeout
Slow suite Check logs Should see only ONE container startup

Rules

  • Use pool: "threads" (not forks)
  • Always call resetSharedDatabase() in beforeEach
  • No afterAll cleanup needed - handled globally
  • Use DI in app code to enable test fakes

Storybook (UI Testing)

bash
pnpm --filter @yourcompany/web storybook

Ensure VITE_API_URL and VITE_AUTH_URL are set in .env.development.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

frmlabz/frm-stack

db-workflow

Database workflow with Postgres, Kysely, and Atlas migrations. Use when modifying database schema, creating migrations, generating TypeScript types, or troubleshooting database issues. Triggers on "schema change", "migration", "db-migrate", "kysely", "atlas", or when editing db/schema.sql.

27 4
Explore
frmlabz/frm-stack

mobile-auth

Better Auth integration with Expo/React Native. Use when working on mobile authentication, session management, or debugging auth issues in the mobile app. Triggers on "mobile auth", "expo auth", "better-auth expo", "session provider", "SecureStore", or when editing apps/frontend/mobile auth files.

27 4
Explore
frmlabz/frm-stack

react-useeffect

React useEffect best practices from official docs. Use when writing/reviewing useEffect, useState for derived values, data fetching, or state synchronization. Teaches when NOT to use Effect and better alternatives.

27 4
Explore
frmlabz/frm-stack

frontend-design

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

27 4
Explore
frmlabz/frm-stack

resolve-pr-comments

Address GitHub PR review comments end-to-end, fetch unresolved review threads (via `gh` GraphQL), implement fixes, reply with what changed, and resolve threads using the bundled scripts. Use when asked to “address PR comments”, “resolve review threads”, or “clear requested changes”.

27 4
Explore
frmlabz/frm-stack

doc-coauthoring

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

27 4
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results