# Testing Best Practices — MeshiTrack

> Instruction file for testing strategy, tools, and patterns across the monorepo.

## Testing Stack

| Layer             | Tool                           | Package           |
| ----------------- | ------------------------------ | ----------------- |
| Unit tests (API)  | Vitest                         | `packages/api`    |
| Unit tests (Web)  | Vitest                         | `packages/web`    |
| Component tests   | React Testing Library          | `packages/web`    |
| Integration tests | Vitest + mongodb-memory-server | `packages/api`    |
| E2E tests         | Playwright                     | root/e2e          |
| API mocking (web) | MSW (Mock Service Worker)      | `packages/web`    |
| Shared validation | Vitest                         | `packages/shared` |

## Directory Structure

```
packages/api/
├── src/
│   └── modules/products/
│       ├── products.routes.test.ts           # Route tests (inject)
│       ├── products.service.test.ts          # Service unit tests
│       └── products.integration.test.ts      # Integration (mongodb-memory-server)
└── vitest.config.ts

packages/web/
├── src/
│   └── components/features/products/
│       ├── ProductCard.tsx
│       └── __tests__/
│           └── ProductCard.test.tsx
└── e2e/                                      # or root-level
    ├── playwright.config.ts
    └── tests/
        └── products.spec.ts
```

## Unit Testing (Fastify API)

### Test one thing at a time

Each test file tests a single class or route module. Mock all dependencies.

### Use `ClassName.name` for `describe` labels

Use the constructor's `.name` property instead of string literals for `describe` block labels. This keeps test output accurate after refactors and avoids stale string mismatches:

```typescript
// correct
describe(NotFoundError.name, () => { ... });

// avoid
describe('NotFoundError', () => { ... });
```

### Service test pattern

```typescript
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { ProductsService } from './products.service.js';
import { ProductsRepository } from './products.repository.js';

describe('ProductsService', () => {
  const mockRepo = {
    findByHousehold: vi.fn(),
    findById: vi.fn(),
    create: vi.fn(),
    update: vi.fn(),
    softDelete: vi.fn(),
    findByBarcode: vi.fn(),
  };

  let service: ProductsService;

  beforeEach(() => {
    vi.clearAllMocks();
    service = new ProductsService({ productsRepository: mockRepo as any });
  });

  describe('create', () => {
    it('should create a product with household scope', async () => {
      const dto = {
        name: 'Chicken Breast',
        category: 'meat',
        servingSize: 100,
        servingUnit: 'g',
        nutrition: { calories: 165, protein: 31, carbs: 0, fat: 3.6 },
      };
      const expected = { id: '1', householdId: 'hh1', createdBy: 'user1', ...dto };
      mockRepo.create.mockResolvedValue(expected);

      const result = await service.create('hh1', 'user1', dto);

      expect(mockRepo.create).toHaveBeenCalledWith(
        expect.objectContaining({
          name: 'Chicken Breast',
          householdId: 'hh1',
          createdBy: 'user1',
        }),
      );
      expect(result.id).toBe('1');
    });

    it('should throw ConflictError for duplicate barcode', async () => {
      mockRepo.findByBarcode.mockResolvedValue({ id: 'existing' });

      await expect(service.create('hh1', 'user1', { ...dto, barcode: '123456' })).rejects.toThrow(
        ConflictError,
      );
    });
  });
});
```

### Route test pattern (using Fastify inject)

```typescript
import { describe, it, expect } from 'vitest';
import Fastify from 'fastify';
import { serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
import productRoutes from './products.routes.js';

describe('Products Routes', () => {
  async function buildTestApp() {
    const app = Fastify({ logger: false });
    app.setValidatorCompiler(validatorCompiler);
    app.setSerializerCompiler(serializerCompiler);
    // Register mocked auth/DI as needed
    await app.register(productRoutes);
    return app;
  }

  it('GET /api/v1/products returns 200', async () => {
    const app = await buildTestApp();
    const response = await app.inject({
      method: 'GET',
      url: '/api/v1/products',
      headers: {
        authorization: 'Bearer <test-jwt>',
        'x-household-id': 'test-household-id',
      },
    });
    expect(response.statusCode).toBe(200);
    expect(response.json()).toHaveProperty('items');
  });
});
```

## Integration Testing (Fastify API)

### Use `mongodb-memory-server` for real MongoDB

```typescript
import { MongoMemoryServer } from 'mongodb-memory-server';
import mongoose from 'mongoose';
import Fastify from 'fastify';
import { serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
import { fastifyAwilixPlugin } from '@fastify/awilix';

describe('ProductsModule Integration', () => {
  let app: ReturnType<typeof Fastify>;
  let mongod: MongoMemoryServer;

  beforeAll(async () => {
    mongod = await MongoMemoryServer.create();
    const uri = mongod.getUri();

    app = Fastify({ logger: false });
    app.setValidatorCompiler(validatorCompiler);
    app.setSerializerCompiler(serializerCompiler);
    await app.register(fastifyAwilixPlugin, { disposeOnClose: true, disposeOnResponse: true, strictBooleanEnforced: true });

    // Connect mongoose to in-memory MongoDB
    await mongoose.connect(uri);

    // Register route modules (with test auth mock)
    await app.register(productRoutes);

    return { app, mongod };
  }

  afterAll(async () => {
    await app.close();
    await mongoose.disconnect();
    await mongod.stop();
  });

  it('POST /api/v1/products → creates and returns product', async () => {
    const res = await app.inject({
      method: 'POST',
      url: '/api/v1/products',
      payload: {
        name: 'Chicken Breast',
        category: 'meat',
        servingSize: 100,
        servingUnit: 'g',
        nutrition: { calories: 165, protein: 31, carbs: 0, fat: 3.6 },
      },
      headers: {
        authorization: 'Bearer <test-jwt>',
        'x-household-id': 'test-hh',
      },
    });

    expect(res.statusCode).toBe(201);
    const body = res.json();
    expect(body.name).toBe('Chicken Breast');
    expect(body.id).toBeDefined();
  });

  it('GET /api/v1/products → returns paginated results', async () => {
    const res = await app.inject({
      method: 'GET',
      url: '/api/v1/products',
      headers: {
        authorization: 'Bearer <test-jwt>',
        'x-household-id': 'test-hh',
      },
    });

    expect(res.statusCode).toBe(200);
    const body = res.json();
    expect(body.data).toBeInstanceOf(Array);
    expect(body.pagination).toHaveProperty('hasMore');
  });
});
```

## Component Testing (Next.js Web)

### React Testing Library patterns

```typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { ProductCard } from '../ProductCard';

const mockProduct = {
  id: '1',
  name: 'Chicken Breast',
  category: 'meat',
  nutrition: { calories: 165, protein: 31, carbs: 0, fat: 3.6 },
};

describe('ProductCard', () => {
  it('displays product name and calories', () => {
    render(<ProductCard product={mockProduct} />);

    expect(screen.getByText('Chicken Breast')).toBeInTheDocument();
    expect(screen.getByText(/165 kcal/)).toBeInTheDocument();
  });

  it('calls onEdit when edit button clicked', async () => {
    const onEdit = vi.fn();
    render(<ProductCard product={mockProduct} onEdit={onEdit} />);

    await userEvent.click(screen.getByRole('button', { name: /edit/i }));

    expect(onEdit).toHaveBeenCalledWith('1');
  });
});
```

### Query priority (from React Testing Library docs)

1. `getByRole` — accessible role + name (best)
2. `getByLabelText` — form fields
3. `getByPlaceholderText` — if no label
4. `getByText` — text content
5. `getByTestId` — last resort

### Avoid testing implementation details

```typescript
// Bad: testing internal state
expect(component.state.isOpen).toBe(true);

// Good: testing visible behavior
expect(screen.getByRole('dialog')).toBeVisible();
```

## API Mocking with MSW

### Setup MSW for web tests

```typescript
// src/mocks/handlers.ts
import { http, HttpResponse } from 'msw';

export const handlers = [
  http.get('*/api/v1/products', () => {
    return HttpResponse.json({
      data: [
        { id: '1', name: 'Chicken', category: 'meat', nutrition: { calories: 165 } },
        { id: '2', name: 'Rice', category: 'grains', nutrition: { calories: 130 } },
      ],
      pagination: { cursor: null, hasMore: false },
    });
  }),

  http.post('*/api/v1/products', async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json({ id: '3', ...body }, { status: 201 });
  }),
];

// src/mocks/server.ts
import { setupServer } from 'msw/node';
import { handlers } from './handlers';
export const server = setupServer(...handlers);

// vitest.setup.ts
beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```

## E2E Testing with Playwright

### Configuration

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './e2e/tests',
  baseURL: 'http://localhost:3000',
  webServer: [
    {
      command: 'docker compose up -d && npm run dev',
      url: 'http://localhost:3000',
      timeout: 120_000,
      reuseExistingServer: !process.env.CI,
    },
  ],
  use: {
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});
```

### Test pattern

```typescript
import { test, expect } from '@playwright/test';

test.describe('Product Library', () => {
  test.beforeEach(async ({ page }) => {
    // Login via Keycloak (use API to get token, set cookie)
    await loginAsTestUser(page);
  });

  test('can create a new product', async ({ page }) => {
    await page.goto('/products');
    await page.click('button:has-text("Add Product")');

    await page.fill('[name="name"]', 'Test Product');
    await page.selectOption('[name="category"]', 'meat');
    await page.fill('[name="servingSize"]', '100');
    await page.fill('[name="nutrition.calories"]', '200');
    await page.click('button:has-text("Save")');

    await expect(page.getByText('Test Product')).toBeVisible();
  });

  test('can search products by name', async ({ page }) => {
    await page.goto('/products');
    await page.fill('[placeholder="Search products..."]', 'chicken');

    await expect(page.getByText('Chicken Breast')).toBeVisible();
    await expect(page.getByText('Rice')).not.toBeVisible();
  });
});
```

## Shared Package Testing

### Test Zod schemas directly

```typescript
import { CreateProductSchema, NutritionInfoSchema } from '../validation';

describe('CreateProductSchema', () => {
  it('accepts valid product input', () => {
    const input = {
      name: 'Chicken Breast',
      category: 'meat',
      servingSize: 100,
      servingUnit: 'g',
      nutrition: { calories: 165, protein: 31, carbs: 0, fat: 3.6 },
    };

    expect(CreateProductSchema.safeParse(input).success).toBe(true);
  });

  it('rejects negative calories', () => {
    const input = {
      name: 'Bad Product',
      category: 'meat',
      servingSize: 100,
      servingUnit: 'g',
      nutrition: { calories: -10, protein: 0, carbs: 0, fat: 0 },
    };

    const result = CreateProductSchema.safeParse(input);
    expect(result.success).toBe(false);
  });

  it('trims whitespace from name', () => {
    const input = {
      name: '  Chicken Breast  ',
      category: 'meat',
      servingSize: 100,
      servingUnit: 'g',
      nutrition: { calories: 165, protein: 31, carbs: 0, fat: 3.6 },
    };

    const result = CreateProductSchema.parse(input);
    expect(result.name).toBe('Chicken Breast');
  });
});
```

## Test Data Factories

### Create reusable test data builders

```typescript
// test/factories/product.factory.ts
import { faker } from '@faker-js/faker';
import { ProductCategory, ServingUnit } from '@meshitrack/shared';

export function buildProduct(overrides: Partial<Product> = {}): Product {
  return {
    id: faker.string.uuid(),
    householdId: 'test-household-1',
    name: faker.food.ingredient(),
    brand: faker.company.name(),
    category: faker.helpers.arrayElement(Object.values(ProductCategory)),
    servingSize: faker.number.int({ min: 1, max: 500 }),
    servingUnit: faker.helpers.arrayElement(Object.values(ServingUnit)),
    nutrition: buildNutrition(),
    tags: [],
    createdBy: 'test-user-1',
    createdAt: new Date(),
    updatedAt: new Date(),
    deletedAt: null,
    ...overrides,
  };
}

export function buildNutrition(overrides: Partial<NutritionInfo> = {}): NutritionInfo {
  return {
    calories: faker.number.int({ min: 0, max: 900 }),
    protein: faker.number.float({ min: 0, max: 60, fractionDigits: 1 }),
    carbs: faker.number.float({ min: 0, max: 100, fractionDigits: 1 }),
    fat: faker.number.float({ min: 0, max: 50, fractionDigits: 1 }),
    ...overrides,
  };
}
```

## Coverage Targets

All packages enforce coverage thresholds via `vitest.config.ts`. CI will fail if coverage drops below these levels.

| Scope             | Lines | Functions | Branches | Statements |
| ----------------- | ----- | --------- | -------- | ---------- |
| `packages/api`    | 100%  | 100%      | 90%      | 100%       |
| `packages/shared` | 100%  | 100%      | 90%      | 100%       |
| `packages/web`    | TBD   | TBD       | TBD      | TBD        |

### Coverage Provider

- **V8** (`@vitest/coverage-v8`) — native V8 engine coverage, fast, zero-config
- Reports: `text`, `lcov`, `json-summary`, `html`
- Reports directory: `./coverage` (gitignored)

### Excluding Code from Coverage

Use `/* v8 ignore start */` / `/* v8 ignore stop */` for code that cannot be unit-tested:

- Entry-point bootstrap blocks (`main.ts` top-level `if`)
- Mongoose schema defaults that only run at document creation
- Framework-internal error handler branches (Zod validation, response serialization)

### Best Practices

- Mark untestable lines with `/* v8 ignore */` comments explaining why
- Keep thresholds at 100% for lines/functions/statements — this forces new code to include tests
- Branch threshold at 90% accommodates config ternaries and null-coalescing guards
- Run `npm run test:cov` before merging to verify thresholds

## Running Tests

**`npx` is banned. Never use it.** Always use `npm run <script>` to invoke Vitest, Playwright, or any other tool.

```bash
# All tests (via turbo)
npm run test

# Specific package
npm run test -w packages/api

# With coverage (specific package)
npm run test:cov -w packages/api

# All packages with coverage (via turbo)
npm run test:cov

# Watch mode (development)
npm run test -- --watch -w packages/api
```