popiart-node-canvas/.planning/codebase/TESTING.md

Testing Patterns

Analysis Date: 2026-01-09

Test Framework

Runner:

• Vitest 4.0.16
• Config: vitest.config.ts in project root

Assertion Library:

• Vitest built-in expect
• Matchers: toBe, toEqual, toHaveLength, toContainEqual, toHaveProperty

Run Commands:

npm test                              # Run all tests in watch mode
npm run test:run                      # Run tests once
npm run test:coverage                 # Run with coverage report

Test File Organization

Location:

• Colocated in __tests__/ directories within feature folders
• Pattern: src/lib/{feature}/__tests__/*.test.ts

Naming:

• {module-name}.test.ts for all tests
• No distinction between unit/integration in filename

Current Test Files:

src/lib/quickstart/__tests__/
  ├── templates.test.ts     # Template data validation
  ├── prompts.test.ts       # Prompt generation tests
  └── validation.test.ts    # JSON validation tests

Test Structure

Suite Organization:

import { describe, it, expect } from "vitest";

describe("validation", () => {
  describe("validateWorkflowJSON", () => {
    describe("root validation", () => {
      it("should reject null input", () => {
        const result = validateWorkflowJSON(null);
        expect(result.valid).toBe(false);
        expect(result.errors).toContainEqual({
          path: "",
          message: "Workflow must be an object",
        });
      });
    });
  });
});

Patterns:

• Nested describe() blocks for logical grouping
• it() with descriptive "should" naming
• Arrange/Act/Assert structure (implicit)
• One concept per test

Mocking

Framework:

• No mocks currently used
• Tests work with actual functions and data

What to Mock (if needed):

• API calls (fetch)
• File system operations
• External services

What NOT to Mock:

• Pure functions
• Validation logic
• Data structures

Fixtures and Factories

Test Data:

• Inline test data in test files
• No separate fixtures directory

Pattern Example:

const validWorkflow = {
  version: 1,
  nodes: [],
  edges: [],
};

Coverage

Requirements:

• No enforced coverage target
• Coverage tracked for awareness

Configuration:

// vitest.config.ts
coverage: {
  provider: "v8",
  reporter: ["text", "json", "html"],
  include: ["src/lib/quickstart/**"],
  exclude: ["node_modules", "src/__tests__"],
}

View Coverage:

npm run test:coverage
open coverage/index.html

Test Types

Unit Tests:

• Current focus: Quickstart validation functions
• Test single functions in isolation
• Examples: validateWorkflowJSON(), repairWorkflowJSON(), parseJSONFromResponse()

Integration Tests:

• Not currently implemented
• Needed for: API routes, workflow execution

E2E Tests:

• Not currently implemented
• Would use Playwright if added

Test Coverage Gaps

Untested Areas:

• src/store/workflowStore.ts - Core execution logic (HIGH PRIORITY)
• src/app/api/** - All API routes
• src/components/** - All React components
• src/utils/costCalculator.ts - Cost calculation
• src/utils/gridSplitter.ts - Grid detection

Tested Areas:

• src/lib/quickstart/validation.ts - Workflow JSON validation
• src/lib/quickstart/templates.ts - Template data structures
• src/lib/quickstart/prompts.ts - Prompt generation

Common Patterns

Async Testing:

it("should handle async operation", async () => {
  const result = await asyncFunction();
  expect(result).toBe("expected");
});

Error Testing:

it("should reject invalid input", () => {
  const result = validateWorkflowJSON(null);
  expect(result.valid).toBe(false);
  expect(result.errors).toContainEqual({
    path: "",
    message: "Workflow must be an object",
  });
});

Snapshot Testing:

• Not used in this codebase
• Prefer explicit assertions

---

Testing analysis: 2026-01-09 Update when test patterns change