testing-skill

name

testing-skill

description

Exhaustive testing patterns for multi-tenant SaaS — unit tests (Vitest), integration tests, E2E tests (Playwright), multi-tenant isolation tests, negative security tests, test data factories, and CI integration. Covers both NestJS backend and Next.js frontend. Trigger when writing tests, setting up test infrastructure, reviewing test coverage, or asking about testing strategies for multi-tenant applications.

SKILL: Exhaustive Testing for Multi-Tenant SaaS

Stack Under Test

Layer	Technology	Test Runner
Backend API	NestJS + Prisma/Drizzle + PostgreSQL + BullMQ + Redis	Vitest
Frontend UI	Next.js 16 + React 19 + TanStack Query + Zustand + TanStack Table	Vitest + Testing Library
End-to-End	Full stack	Playwright
Multi-tenant isolation	API + DB	Vitest + supertest

---

IDENTITY

You are a senior test engineer specializing in multi-tenant SaaS platforms. You:

1. Treat tests as the primary documentation of system behavior
2. Prioritize isolation tests above all else — a data leak is worse than a broken feature
3. Never trust "it works on my machine" — automated tests in CI or it does not exist
4. Write tests that catch real bugs, not tests that pad coverage numbers
5. Design test data factories that mirror the production tenant hierarchy

---

TESTING PYRAMID — MEMORIZE THIS

                    ┌───────────┐
                    │    E2E    │  ~10% — Happy paths, critical user journeys
                    │(Playwright)│  Auth flow, workspace switch, import wizard
                    ├───────────┤
                    │ Integration│  ~30% — API endpoints, DB queries, job processors
                    │(Vitest+DB) │  Multi-tenant isolation, BullMQ flows, SSE
                    ├───────────┤
                    │   Unit     │  ~60% — Services, utils, Zod schemas, hooks, stores
                    │ (Vitest)   │  Fast, mocked dependencies, deterministic
                    └───────────┘

Fourth Layer: Isolation Tests (Cuts Across All Three)

Isolation tests verify that workspace A cannot see workspace B data. They run at integration level (real DB) but are so critical they get their own category, dedicated files, and mandatory CI gate.

ANY module shipped without isolation tests = BLOCKED from merge.

---

WHEN TO WRITE EACH TEST TYPE

Unit Tests — ALWAYS

Write unit tests for:

• Every service method (business logic)
• Every utility/helper function
• Every Zod schema (valid + invalid inputs)
• Every React hook (TanStack Query wrappers, Zustand stores)
• Every pure component (rendering, conditional UI)

Do NOT unit test:

• Controllers (test at integration level with supertest)
• Repository methods (test at integration level with real DB)
• CSS/styling (test visually with Playwright screenshots)

Integration Tests — For Every API Endpoint

Write integration tests for:

• Every controller endpoint (HTTP method + route + response shape)
• Every repository method (real DB, real queries)
• Every BullMQ processor (real job execution, mock external APIs)
• Every guard/middleware (TenantContextGuard, auth guards)
• Every endpoint's workspace boundary (isolation test)

E2E Tests — For Every User Journey

Write E2E tests for:

• Authentication flow (login, session persistence, logout)
• Workspace switching (context changes, data refreshes)
• CRUD operations (create, read, update, delete via UI)
• Data table interactions (search, filter, sort, bulk select, pagination)
• Import wizard (upload, map, review, commit)
• Settings changes (inheritance, override, reset)

Isolation Tests — For Every Data-Touching Endpoint

Write isolation tests for:

• Every GET endpoint (must not return cross-workspace data)
• Every POST/PATCH/DELETE endpoint (must not mutate cross-workspace data)
• Every bulk operation (must not touch cross-workspace records)
• Every aggregation/report (must scope to correct tenant level)
• Every search/filter (must not leak cross-tenant results)

---

BACKEND TESTING PATTERNS

Test File Organization

src/modules/{feature}/
  ├── __tests__/
  │   ├── {feature}.service.spec.ts        # Unit tests — mocked repo
  │   ├── {feature}.controller.spec.ts     # Integration — supertest + real DB
  │   ├── {feature}.repository.spec.ts     # Integration — real DB
  │   ├── {feature}.processor.spec.ts      # BullMQ job tests
  │   └── {feature}.isolation.spec.ts      # Multi-tenant isolation
  ├── {feature}.module.ts
  ├── {feature}.controller.ts
  ├── {feature}.service.ts
  ├── {feature}.repository.ts
  └── {feature}.processor.ts

NestJS Service Test Template (Unit)

import { Test } from '@nestjs/testing';
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { RecipientsService } from '../recipients.service';
import { RecipientsRepository } from '../recipients.repository';
import { AuditService } from '../../audit/audit.service';
import { PlanManager } from '../../billing/plan.manager';

describe('RecipientsService', () => {
  let service: RecipientsService;
  let repo: RecipientsRepository;
  let auditService: AuditService;

  const mockTenantContext = {
    domainId: 'domain-1',
    workspaceId: 'ws-1',
    companyId: 'company-1',
    subscriptionTier: 'pro' as const,
    subscriptionStatus: 'active' as const,
    seatsLimit: ,
    : ,
  };

  ( () => {
      =  .({
      : [
        ,
        {
          : ,
          : {
            : vi.(),
            : vi.(),
            : vi.(),
            : vi.(),
            : vi.(),
            : vi.(),
          },
        },
        {
          : ,
          : { : vi.(), : vi.() },
        },
        {
          : ,
          : {
            : vi.().({
              :  ,
              :  ,
            }),
          },
        },
      ],
    }).();

    service = .();
    repo = .();
    auditService = .();
  });

  (,  {
    (,  () => {
      vi.(repo.).();
      vi.(repo.).({ : , :  });

       result =  service.(mockTenantContext, {
        : ,
        : ,
        : ,
      });

      (result).({ : , :  });
      (repo.).(
        expect.({
          : ,
          : ,
          : ,
        }),
      );
    });

    (,  () => {
      vi.(repo.).();

       (
        service.(mockTenantContext, { : , : , :  }),
      )..();
    });

    (,  () => {
      vi.(repo.).();
      vi.(repo.).({ : , :  });

       service.(mockTenantContext, { : , : , :  });

      (auditService.).(
        expect.({
          : ,
          : ,
        }),
      );
    });
  });

  (,  {
    (,  () => {
      vi.(repo.).({ :  });

       result =  service.(mockTenantContext, [, , ]);

      (repo.).(, [, , ]);
    });
  });
});

NestJS Controller Test Template (Integration)

import { Test } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { AppModule } from '../../../app.module';
import { TestDbHelper } from '../../../../test/helpers/test-db';
import { createTestTenant } from '../../../../test/factories/tenant.factory';

describe('RecipientsController (Integration)', () => {
  let app: INestApplication;
  let db: TestDbHelper;
  let tenant: Awaited<ReturnType<typeof createTestTenant>>;

  beforeAll(async () => {
    const module = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = .();
     app.();

    db =  ();
    tenant =  (db);
  });

  ( () => {
     db.();
     app.();
  });

  (,  {
    (,  () => {
       db.(tenant.., tenant.., tenant.., {
        : ,
      });

       res =  (app.())
        .()
        .(, )
        .();

      (res..).();
      (res..[].).();
      (res..).({
        : ,
        : ,
        : expect.(),
      });
    });

    (,  () => {
       (app.())
        .()
        .();
    });

    (,  () => {
       emptyDomain =  db.(tenant.., tenant..);

       res =  (app.())
        .()
        .(, )
        .();

      (res..).();
    });
  });

  (,  {
    (,  () => {
       res =  (app.())
        .()
        .(, )
        .({ : , : , :  })
        .();

      (res..).({
        : ,
        : tenant..,
        : tenant..,
        : tenant..,
      });
    });

    (,  () => {
       (app.())
        .()
        .(, )
        .({ : , : , :  })
        .();
    });

    (,  () => {
       db.(tenant.., tenant.., tenant.., {
        : ,
      });

       (app.())
        .()
        .(, )
        .({ : , : , :  })
        .();
    });
  });
});

Repository Test Template (Integration with Real DB)

import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
import { TestDbHelper } from '../../../../test/helpers/test-db';
import { RecipientsRepository } from '../recipients.repository';
import { createTestTenant } from '../../../../test/factories/tenant.factory';

describe('RecipientsRepository', () => {
  let db: TestDbHelper;
  let repo: RecipientsRepository;
  let tenant: Awaited<ReturnType<typeof createTestTenant>>;

  beforeAll(async () => {
    db = await TestDbHelper.create();
    repo = new RecipientsRepository(db.drizzle);
    tenant = await createTestTenant(db);
  });

  beforeEach(async () => {
    await db.truncate('recipients');
  });

  afterAll(async () => {
    await db.cleanup();
  });

  describe(,  {
    (,  () => {
      
       db.(tenant.., tenant.., tenant.., {
        : ,
      });
       db.(tenant.., tenant.., tenant.., {
        : ,
      });

       result =  repo.(tenant.., {});

      (result.).();
      (result.[].).();
    });

    (,  () => {
       db.(tenant.., tenant.., tenant.., {
        : ,
        : ,
      });
       db.(tenant.., tenant.., tenant.., {
        : ,
        : ,
      });

       result =  repo.(tenant.., { :  });

      (result.).();
      (result.[].).();
    });

    (,  () => {
       ( i = ; i < ; i++) {
         db.(tenant.., tenant.., tenant.., {
          : ,
        });
      }

       result =  repo.(tenant.., { : , :  });

      (result.).();
      (result.).();
    });

    (,  () => {
       db.(tenant.., tenant.., tenant.., {
        : ,
      });
       db.(tenant.., tenant.., tenant.., {
        : ,
      });

       result =  repo.(tenant.., { :  });

      (result.).();
      (result.[].).();
    });
  });

  (,  {
    (,  () => {
       db.(tenant.., tenant.., tenant.., {
        : ,
      });
       db.(tenant.., tenant.., tenant.., {
        : ,
      });

       count =  repo.(tenant..);

      (count).();
    });
  });
});

BullMQ Job Processor Test Template

import { Test } from '@nestjs/testing';
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { Job } from 'bullmq';
import { BulkUpdateProcessor } from '../bulk-update.processor';
import { RecipientsRepository } from '../recipients.repository';
import { JobLogRepository } from '../../job-logs/job-log.repository';

describe('BulkUpdateProcessor', () => {
  let processor: BulkUpdateProcessor;
  let repo: RecipientsRepository;
  let redis: { set: ReturnType<typeof vi.fn>; get: ReturnType<typeof vi.fn> };

  beforeEach(async () => {
    redis = { set: vi.fn(), get: vi.fn() };

    const module = await .({
      : [
        ,
        {
          : ,
          : {
            : vi.(),
            : vi.(),
          },
        },
        {
          : ,
          : { : vi.() },
        },
        { : , : redis },
        { : , : { : vi.() } },
      ],
    }).();

    processor = .();
    repo = .();
  });

  (,  () => {
    vi.(repo.).();
    vi.(repo.).();

     job = {
      : ,
      : {
        : ,
        : { :  },
        : { :  },
        : { : , :  },
      },
      : { :  },
      : ,
      : ,
      : ,
    }    ;

     processor.(job);

    
    (repo.).();
  });

  (,  () => {
    vi.(repo.).();
    vi.(repo.).();

     job = {
      : ,
      : {
        : ,
        : {},
        : { :  },
        : { : , :  },
      },
      : { :  },
      : ,
      : ,
      : ,
    }    ;

     processor.(job);

    
    (redis.).(
      ,
      expect.(),
      ,
      ,
    );
  });

  (,  () => {
    vi.(repo.).( ());

     job = {
      : ,
      : {
        : ,
        : {},
        : {},
        : { : , :  },
      },
      : { :  },
      : ,
      : ,
      : ,
    }    ;

     (processor.(job))..();
  });
});

---

FRONTEND TESTING PATTERNS

React Component Test Template (Testing Library)

import { render, screen, within } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { describe, it, expect, vi } from 'vitest';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { RecipientForm } from '../recipient-form';

function createWrapper() {
  const queryClient = new QueryClient({
    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
  });
  return ({ children }: { children: React.ReactNode }) => (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
}

describe('RecipientForm', () => {
  it('should render all form fields', () => {
    render(<RecipientForm onSubmit= />, { : () });

    (screen.()).();
    (screen.()).();
    (screen.()).();
    (screen.(, { :  })).();
  });

  (,  () => {
     user = userEvent.();
    (, { : () });

     user.(screen.(, { :  }));

    ( screen.()).();
  });

  (,  () => {
     handleSubmit = vi.();
     user = userEvent.();
    (, { : () });

     user.(screen.(), );
     user.(screen.(), );
     user.(screen.(), );
     user.(screen.(, { :  }));

    (handleSubmit).(
      expect.({
        : ,
        : ,
        : ,
      }),
    );
  });

  (,  () => {
     user = userEvent.();
    (, { : () });

    (screen.(, { :  })).();
  });
});

React Hook Test Template (TanStack Query)

import { renderHook, waitFor } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { useRecipients, useCreateRecipient } from '../hooks/use-recipients';
import { recipientsApi } from '../lib/api';

vi.mock('../lib/api');

function createWrapper() {
  const queryClient = new QueryClient({
    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
  });
  return ({ children }: { children: React.ReactNode }) => (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
}

describe('useRecipients', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('should fetch recipients and return data',  () => {
    vi.(recipientsApi.).([
      { : , : , : , :  },
    ]);

     { result } = ( (), { : () });

     ( (result..).());
    (result..).();
    (result..![].).();
  });

  (,  () => {
    vi.(recipientsApi.).([]);

     filter = { : [], :  };
    ( (filter), { : () });

     ( (recipientsApi.).(filter));
  });

  (,  () => {
    vi.(recipientsApi.).( ());

     { result } = ( (), { : () });

     ( (result..).());
    (result..?.).();
  });
});

(,  {
  (,  () => {
    vi.(recipientsApi.).({
      : ,
      : ,
      : ,
      : ,
    });

     queryClient =  ({
      : { : { :  }, : { :  } },
    });
     spy = vi.(queryClient, );

      = () => (
      
    );

     { result } = ( (), { wrapper });

    result..({ : , : , :  });

     ( (result..).());
    (spy).(
      expect.({ : expect.([]) }),
    );
  });
});

Zustand Store Test Template

import { describe, it, expect, beforeEach } from 'vitest';
import { useWorkspaceStore } from '../workspace-store';

describe('WorkspaceStore', () => {
  beforeEach(() => {
    // Reset store state between tests
    useWorkspaceStore.setState({
      activeWorkspaceId: null,
      activeCompanyId: null,
      workspaces: [],
    });
  });

  it('should set active workspace', () => {
    const store = useWorkspaceStore.getState();
    store.setActiveWorkspace('ws-1');
    expect(useWorkspaceStore.getState().activeWorkspaceId).toBe('ws-1');
  });

  it('should clear active workspace on company switch', () => {
    useWorkspaceStore.setState({ activeWorkspaceId: 'ws-1', activeCompanyId: 'c-1' });

    const store = useWorkspaceStore.getState();
    store.setActiveCompany('c-2');

    expect(useWorkspaceStore.getState().activeWorkspaceId).toBeNull();
    (useWorkspaceStore.().).();
  });

  (,  {
    useWorkspaceStore.({
      : [
        { : , : , :  },
        { : , : , :  },
      ],
    });

     store = useWorkspaceStore.();
    (store..).();
    
  });
});

Zod Schema Test Template

import { describe, it, expect } from 'vitest';
import { CreateRecipientSchema, RecipientFilterSchema } from '../types';

describe('CreateRecipientSchema', () => {
  it('should accept valid input', () => {
    const result = CreateRecipientSchema.safeParse({
      email: '[e-mail]',
      firstName: 'Rajesh',
      lastName: 'Kumar',
      status: 'active',
    });
    expect(result.success).toBe(true);
  });

  it('should reject invalid email', () => {
    const result = CreateRecipientSchema.safeParse({
      email: 'not-email',
      firstName: 'Test',
      lastName: 'User',
    });
    expect(result.success).toBe(false);
    if (!result.success) {
      expect(result.error.issues[].).();
    }
  });

  (,  {
     result = .({
      : ,
      : ,
      : ,
    });
    (result.).();
  });

  (,  {
     result = .({
      : ,
      : ,
      : ,
    });
    (result.).();
  });
});

(,  {
  (,  {
     result = .({});
    (result.).();
  });

  (,  {
     result = .({ : , :  });
    (result.).();
    (result.).();
  });

  (,  {
     result = .({ : - });
    (result.).();
  });
});

---

TEST DATA FACTORIES

Tenant Hierarchy Factory

// test/factories/tenant.factory.ts
import { TestDbHelper } from '../helpers/test-db';
import { randomUUID } from 'crypto';

interface TestTenant {
  company: { id: string; name: string; slug: string };
  workspaceA: { id: string; name: string; companyId: string };
  workspaceB: { id: string; name: string; companyId: string };
  domainA: { id: string; domainName: string; workspaceId: string; companyId: string };
  domainB: { id: string; domainName: string; workspaceId: string; companyId: string };
  domainC: { id: string; domainName: string; workspaceId: ; :  };
  : ; 
  : ; 
  : ; 
}


   (): <> {
   company =  db.({
    : ,
    : ,
    : ,
    : ,
    : ,
  });

   workspaceA =  db.(company., {
    : ,
    : ,
  });

   workspaceB =  db.(company., {
    : ,
    : ,
  });

   domainA =  db.(workspaceA., company., {
    : ,
    : ,
  });

   domainB =  db.(workspaceB., company., {
    : ,
    : ,
  });

   domainC =  db.(workspaceB., company., {
    : ,
    : ,
  });

   tokenA =  db.(workspaceA., );
   tokenB =  db.(workspaceB., );
   companyToken =  db.(company., );

   {
    company,
    workspaceA,
    workspaceB,
    domainA,
    domainB,
    domainC,
    tokenA,
    tokenB,
    companyToken,
  };
}


   () {
   company =  db.({
    : ,
    : ,
    : ,
    : ,
    : ,
  });

   workspace =  db.(company., {
    : ,
    : ,
  });

   domain =  db.(workspace., company., {
    : ,
    : ,
  });

   token =  db.(workspace., );

   { company, workspace, domain, token };
}


   () {
   company =  db.({
    : ,
    : ,
    : ,
    : ,
    : ,
  });

   workspace =  db.(company., {
    : ,
    : ,
  });

   domainJio =  db.(workspace., company., {
    : ,
    : ,
  });

   domainSaavn =  db.(workspace., company., {
    : ,
    : ,
  });

   token =  db.(workspace., );

   { company, workspace, domainJio, domainSaavn, token };
}

Recipient Factory

// test/factories/recipient.factory.ts
import { TestDbHelper } from '../helpers/test-db';
import { randomUUID } from 'crypto';

const INDIAN_NAMES = [
  { firstName: 'Rajesh', lastName: 'Kumar' },
  { firstName: 'Priya', lastName: 'Sharma' },
  { firstName: 'Vikram', lastName: 'Singh' },
  { firstName: 'Anita', lastName: 'Patel' },
  { firstName: 'Suresh', lastName: 'Reddy' },
  { firstName: 'Meera', lastName: 'Nair' },
  { firstName: 'Arjun', lastName: 'Gupta' },
  { firstName: 'Deepa', lastName: 'Iyer' },
  { firstName: 'Amit', lastName: 'Joshi' },
  { firstName: 'Kavita', lastName: 'Deshmukh' },
];

const DEPARTMENTS = [
  'Engineering', , , ,
  , , , ,
];

  {
  ?: ;
  ?: ;
  ?: ;
  ?: ;
  ?: ;
  ?: <, >;
}

  () {
   name = [.(.() * .)];
   {
    : (),
    domainId,
    workspaceId,
    companyId,
    : overrides?. ?? ,
    : overrides?. ?? name.,
    : overrides?. ?? name.,
    : overrides?. ?? ,
    : overrides?. ?? [.(.() * .)],
    : overrides?. ?? {},
  };
}


   () {
   recipients = .({ : count }, 
    (domainId, workspaceId, companyId, {
      : ,
      ...overrides,
    }),
  );
   db.(, recipients);
}

---

MULTI-TENANT ISOLATION TESTS (THE MOST CRITICAL SECTION)

See multi-tenant-testing.md for the complete isolation test framework, templates, and all 6 negative security tests as runnable code.

Why Isolation Tests Are #1 Priority

A broken feature is a bug. A broken tenant boundary is a security incident, a compliance violation, and potentially a company-ending event. Every endpoint that touches data must prove it cannot leak across tenant boundaries.

Quick Reference: What Must Be Isolated

Resource	Isolation Level	Test Pattern
Recipients	Domain (hot path), Workspace (dashboard)	GET returns only same-domain data
Campaigns	Workspace	Campaign in WS-A invisible to WS-B admin
Training	Workspace	Training targets scoped to workspace
Settings	Workspace	WS-A settings independent of WS-B
Reports	Company (aggregated), Workspace (scoped)	Company admin sees all; workspace admin sees own
Audit logs	Workspace (scoped), Company (admin)	WS-A admin cannot see WS-B audit trail
Import jobs	Domain	Import into domain-A does not affect domain-B
Bulk operations	Domain + Workspace	Bulk delete in WS-A cannot touch WS-B records

---

REACT QUERY TESTING

QueryClient Test Configuration

// test/helpers/query-client.ts
import { QueryClient } from '@tanstack/react-query';

export function createTestQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        retry: false,          // Don't retry in tests
        gcTime: Infinity,      // Don't garbage collect during test
        staleTime: Infinity,   // Don't refetch automatically
      },
      mutations: {
        retry: false,
      },
    },
    logger: {
      log: console.log,
      warn: console.warn,
      error: () => {},        // Suppress error noise in tests
    },
  });
}

export function createTestWrapper() {
  const queryClient = createTestQueryClient();
  return {
    queryClient,
    wrapper: ({ children }: { children: React.ReactNode }) => (
      <QueryClientProvider client=>{children}
    ),
  };
}

Testing Mutations with Cache Invalidation

it('should invalidate recipient list after successful delete', async () => {
  const { queryClient, wrapper } = createTestWrapper();

  // Pre-populate cache
  queryClient.setQueryData(['recipients', 'list', {}], [
    { id: '1', email: '[e-mail]' },
    { id: '2', email: '[e-mail]' },
  ]);

  vi.mocked(recipientsApi.delete).mockResolvedValue(undefined);

  const { result } = renderHook(() => useDeleteRecipient(), { wrapper });

  result.current.mutate('1');

  await waitFor(() => expect(result.current.isSuccess).toBe(true));

  // Verify cache was invalidated (not just the deleted item)
  const cachedData = queryClient.getQueryData(['recipients', 'list', {}]);
  expect(cachedData).toBeUndefined(); // Invalidated, will refetch
});

---

ZUSTAND STORE TESTING

Testing Store with Middleware

import { describe, it, expect, beforeEach } from 'vitest';
import { act } from '@testing-library/react';
import { useWorkspaceStore } from '../stores/workspace-store';

describe('WorkspaceStore (with persist middleware)', () => {
  beforeEach(() => {
    // Reset Zustand store to initial state
    const { setState } = useWorkspaceStore;
    setState({
      activeWorkspaceId: null,
      activeCompanyId: null,
      workspaces: [],
    }, true); // true = replace state (not merge)
  });

  it('should update active workspace and trigger side effects', () => {
    act(() => {
      useWorkspaceStore.getState().setActiveWorkspace('ws-new');
    });

    const state = useWorkspaceStore.getState();
    expect(state.activeWorkspaceId).toBe('ws-new');
  });

  it('should compute showWorkspaceSelector from workspace count', () => {
    act(() => {
      useWorkspaceStore.setState({
        workspaces: [
          { : , : , :  },
          { : , : , :  },
        ],
      });
    });

     { workspaces } = useWorkspaceStore.();
     showWorkspaceSelector = workspaces. > ;
    (showWorkspaceSelector).(); 
  });

  (,  {
    ( {
      useWorkspaceStore.({
        : [{ : , : , :  }],
      });
    });

     { workspaces } = useWorkspaceStore.();
     showWorkspaceSelector = workspaces. > ;
    (showWorkspaceSelector).(); 
  });
});

---

PLAYWRIGHT E2E PATTERNS

See e2e-testing.md for complete Playwright setup, page object pattern, auth flows, data table E2E, and CI integration.

Quick Reference: What E2E Tests Cover

User Journey	File	Priority
Login + session	auth.spec.ts	P0
Workspace switching	workspace-switch.spec.ts	P0
Recipient CRUD	recipients.spec.ts	P0
Data table (search, filter, sort)	data-table.spec.ts	P1
Bulk operations	bulk-ops.spec.ts	P1
CSV import wizard	import-wizard.spec.ts	P1
Settings (inheritance)	settings.spec.ts	P1
Campaign creation	campaign.spec.ts	P2
Training assignment	training.spec.ts	P2

---

CI INTEGRATION

Vitest Configuration for NestJS + Next.js

// vitest.config.ts (backend)
import { defineConfig } from 'vitest/config';
import { resolve } from 'path';

export default defineConfig({
  test: {
    globals: true,
    root: resolve(__dirname),
    include: ['src/**/*.spec.ts'],
    exclude: ['src/**/*.e2e-spec.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json-summary', 'html'],
      thresholds: {
        branches: 70,
        functions: 70,
        lines: 80,
        statements: 80,
      },
    },
    setupFiles: ['./test/setup.ts'],
    // Test database configuration
    pool: 'forks',       // Isolate test suites
    poolOptions: {
      forks: { maxForks: 4 },
    },
  },
});

// vitest.config.ts (frontend)
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
import { resolve } from 'path';

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    include: ['src/**/*.test.{ts,tsx}'],
    setupFiles: ['./test/setup.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json-summary', 'html'],
      thresholds: {
        branches: 60,
        functions: 60,
        lines: 70,
        statements: 70,
      },
    },
    alias: {
      '@': resolve(__dirname, './src'),
    },
  },
});

GitHub Actions CI Pipeline

# .github/workflows/test.yml
name: Test Suite
on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - name: Backend unit tests
        run: pnpm --filter backend test:unit
      - name: Frontend unit tests
        run: pnpm --filter frontend test:unit
      - name: Upload coverage
         
        
           
           
  
     
    
      
         
        
           
           
           
         []
               
         
         []
             
        
        
        
           
           
          
         
            
        
           
           
            
        
           
           

  
     
     [, ]
    
      
         
        
           
           
           
         []
      
         
         []
    
        
        
        
           
           
          
          
              
          
            
        
           
           
          
         
         
        
           
           

---

TEST NAMING CONVENTIONS

Backend (Vitest)

describe('ClassName or ModuleName')
  describe('methodName')
    it('should [expected behavior] when [condition]')

Examples:

describe('RecipientsService')
  describe('create')
    it('should create recipient when under limit')
    it('should throw PaymentRequiredException when limit exceeded')
    it('should log audit event on creation')
  describe('bulkDelete')
    it('should delete only IDs belonging to the domain')
    it('should return affected count')
    it('should enqueue BullMQ job when count exceeds 1000')

Frontend (Vitest + Testing Library)

describe('ComponentName or HookName')
  it('should render [element] when [condition]')
  it('should call [handler] when [user action]')
  it('should show [feedback] after [mutation]')

E2E (Playwright)

test.describe('Feature or User Journey')
  test('should [complete action] as [role]')

---

MOCK PATTERNS: WHEN TO MOCK, WHEN NOT TO

Mock These (Unit Tests)

• Database repositories
• External API clients (email senders, storage, SSO providers)
• Redis client
• BullMQ queues
• AuditService (fire-and-forget behavior is hard to assert otherwise)
• Date.now() / randomUUID() when deterministic output matters

Do NOT Mock These (Use Real Implementations)

• Zod schemas (test validation logic directly)
• Utility/helper functions (they are pure — no side effects)
• TanStack Query hooks (wrap in QueryClientProvider, mock the API layer)
• Zustand stores (test directly, they are synchronous)
• NestJS guards (test at integration level with real guard chain)

Mock Boundary Rule

Unit test:  mock at the REPOSITORY boundary
Integration test: mock at the EXTERNAL SERVICE boundary (real DB, real Redis)
E2E test: mock NOTHING (full stack, real DB, real Redis, real queues)

---

MASTER CHECKLIST — Run Before Shipping Any Feature

Unit Tests

• Every service method has >=1 happy path + >=1 error path test
• Every Zod schema tested with valid + invalid inputs
• Every React hook tested with QueryClientProvider wrapper
• Every Zustand store action tested
• Mocks are at repository boundary (not deeper, not shallower)
• No any types in test files
• Test names follow should [behavior] when [condition] pattern

Integration Tests

• Every controller endpoint tested (status code + response shape)
• Auth required: 401 without token
• Validation: 400 for invalid input
• Not found: 404 for missing resource
• Conflict: 409 for duplicates
• Real database used (test container or CI service)
• Data cleaned up after each test (truncate or transaction rollback)

Multi-Tenant Isolation (MANDATORY)

• Every GET endpoint: WS-A token cannot fetch WS-B data
• Every POST endpoint: cannot create data in wrong workspace
• Every PATCH endpoint: cannot update data in wrong workspace
• Every DELETE endpoint: cannot delete data in wrong workspace
• Bulk operations: cannot touch cross-workspace records
• Company endpoints: aggregate correctly, do not leak individual workspace data
• Domain-level: domain-A query returns zero domain-B recipients

E2E Tests

• Auth flow: login, session persist, logout
• Workspace switch: data refreshes, no stale data visible
• CRUD: create, edit, delete via UI — verify in data table
• Data table: search works, filters work, sort works
• Bulk actions: select multiple, execute, verify result
• Import: upload CSV, map columns, review, commit
• Progressive complexity: UC1 user sees no multi-tenant UI

CI Pipeline

• Unit tests pass in <2 minutes
• Integration tests pass with real DB (postgres service in CI)
• E2E tests pass with Playwright (artifacts uploaded on failure)
• Coverage thresholds enforced (80% backend, 70% frontend)
• Isolation tests are a separate CI step that blocks merge on failure