Testing

Testing practices and guidelines for Cal.com

Testing Strategy

Cal.com uses a comprehensive testing strategy:

1. Unit Tests - Vitest for business logic and utilities
2. Integration Tests - Testing API endpoints and services
3. E2E Tests - Playwright for end-to-end user flows
4. Type Checking - TypeScript compiler for type safety

Unit Testing with Vitest

Running Unit Tests

# Run all unit tests
TZ=UTC yarn test

# Run tests in watch mode
yarn tdd

# Run tests with UI
TZ=UTC yarn test:ui

Always set TZ=UTC to ensure consistent timezone behavior across environments.

Writing Unit Tests

Create test files with .test.ts or .spec.ts suffix:

// File: packages/lib/date/parseDate.test.ts
import { describe, it, expect } from "vitest";
import { parseDate } from "./parseDate";

describe("parseDate", () => {
  it("should parse ISO date string", () => {
    const result = parseDate("2024-03-04T10:00:00Z");
    expect(result).toBeInstanceOf(Date);
  });

  it("should throw error for invalid date", () => {
    expect(() => parseDate("invalid")).toThrow();
  });
});

Mocking Prisma

Use Prismock for Prisma mocking:

import { PrismaClient } from "@prisma/client";
import { beforeEach } from "vitest";
import { mockDeep, mockReset } from "vitest-mock-extended";

const prismaMock = mockDeep<PrismaClient>();

beforeEach(() => {
  mockReset(prismaMock);
});

// Mock Prisma queries
prismaMock.booking.findUnique.mockResolvedValue({
  id: 1,
  title: "Test Booking",
  startTime: new Date(),
  // ...
});

Mocking Fetch

Use vitest-fetch-mock:

import { describe, it, expect, beforeAll } from "vitest";
import { enableFetchMocks } from "vitest-fetch-mock";

beforeAll(() => {
  enableFetchMocks();
});

it("should fetch data from API", async () => {
  fetchMock.mockResponseOnce(JSON.stringify({ data: "test" }));
  
  const response = await fetch("/api/test");
  const data = await response.json();
  
  expect(data).toEqual({ data: "test" });
});

E2E Testing with Playwright

Running E2E Tests

# Run all E2E tests
yarn test-e2e

# Run web app E2E tests
yarn e2e

# Run app-store E2E tests
yarn test-e2e:app-store

# Run embed E2E tests
yarn test-e2e:embed

# View test report
yarn playwright show-report test-results/reports/playwright-html-report

Installing Playwright Browsers

If you encounter browser errors:

npx playwright install

Error example:

Executable doesn't exist at /Users/alice/Library/Caches/ms-playwright/chromium-1048/chrome-mac/Chromium.app/Contents/MacOS/Chromium

Writing E2E Tests

Create test files with .e2e.ts suffix:

// File: apps/web/tests/bookings/create-booking.e2e.ts
import { expect, test } from "@playwright/test";

test.describe("Booking Creation", () => {
  test("should create a new booking", async ({ page }) => {
    // Navigate to booking page
    await page.goto("/free/30min");
    
    // Select time slot
    await page.click("[data-testid=time-slot]:first-child");
    
    // Fill booking form
    await page.fill("[name=name]", "John Doe");
    await page.fill("[name=email]", "[e-mail]");
    
    // Submit booking
    await page.click("[data-testid=confirm-booking]");
    
    // Verify success message
    await expect(page.locator("text=Booking confirmed")).toBeVisible();
  });
});

E2E Test Configuration

Set environment variables in .env:

NEXT_PUBLIC_IS_E2E=1
E2E_TEST_MAILHOG_ENABLED=1
NEXTAUTH_URL=http://localhost:3000

E2E Test Utilities

Cal.com provides E2E test utilities in packages/testing/:

import { test } from "@calcom/test/e2e/lib/fixtures";
import { createBooking } from "@calcom/test/e2e/lib/helpers";

test("should reschedule booking", async ({ page, users }) => {
  const user = await users.create();
  const booking = await createBooking({ userId: user.id });
  
  // Test reschedule flow
});

Type Checking

Running Type Checks

# Type check all packages
yarn type-check

# Type check for CI (with force flag)
yarn type-check:ci --force

Always run yarn type-check:ci --force before concluding that CI failures are unrelated to your changes.

Fixing Type Errors

1. Run yarn prisma generate if you see missing enum/type errors
2. Fix type errors before test failures - they’re often the root cause
3. Never use as any to bypass type errors

Integration Testing

Testing tRPC Endpoints

import { describe, it, expect } from "vitest";
import { createContextInner } from "@calcom/trpc/server/createContext";
import { appRouter } from "@calcom/trpc/server/routers/_app";

describe("Bookings Router", () => {
  it("should create a booking", async () => {
    const ctx = await createContextInner({ session: mockSession });
    const caller = appRouter.createCaller(ctx);
    
    const booking = await caller.viewer.bookings.create({
      eventTypeId: 1,
      startTime: "2024-03-04T10:00:00Z",
      timeZone: "UTC",
    });
    
    expect(booking).toBeDefined();
    expect(booking.id).toBeGreaterThan(0);
  });
});

Testing API Routes

import { describe, it, expect } from "vitest";
import { createMocks } from "node-mocks-http";
import handler from "@/pages/api/bookings";

describe("/api/bookings", () => {
  it("should return bookings for authenticated user", async () => {
    const { req, res } = createMocks({
      method: "GET",
      headers: {
        authorization: "Bearer test-token",
      },
    });
    
    await handler(req, res);
    
    expect(res._getStatusCode()).toBe(200);
    expect(res._getJSONData()).toHaveProperty("bookings");
  });
});

Database Testing

Using Test Database

Set up a separate test database:

# .env.test
DATABASE_URL="postgresql://user:pass@localhost:5432/calcom_test"

Database Seeding

Seed the database for testing:

# Seed with default data
yarn db-seed

# View seeded data
yarn db-studio

Reset Database Between Tests

import { beforeEach } from "vitest";
import { prisma } from "@calcom/prisma";

beforeEach(async () => {
  // Clean up database
  await prisma.booking.deleteMany();
  await prisma.user.deleteMany();
});

Testing Commands Reference

Unit Tests

TZ=UTC yarn test                 # Run all unit tests
yarn tdd                          # Watch mode
TZ=UTC yarn test:ui               # Run with UI

E2E Tests

yarn test-e2e                     # All E2E tests (with seeding)
yarn e2e                          # Web app E2E tests
yarn test-e2e:app-store           # App store E2E tests
yarn test-e2e:embed               # Embed E2E tests
yarn test-e2e:embed-react         # Embed React E2E tests
npx playwright install            # Install browsers

Type Checking

yarn type-check                   # Type check all packages
yarn type-check:ci --force        # Type check for CI

Linting & Formatting

yarn lint                         # Run linter
yarn lint:fix                     # Fix linting issues
yarn biome check --write .        # Format and lint with Biome

Test Coverage

Generate test coverage reports:

TZ=UTC yarn test --coverage

View coverage report in coverage/index.html.

Continuous Integration

Cal.com uses GitHub Actions for CI/CD:

CI Workflow

1. Lint - Check code formatting and style
2. Type Check - Verify TypeScript types
3. Unit Tests - Run Vitest tests
4. E2E Tests - Run Playwright tests
5. Build - Ensure production build succeeds

Local Pre-Push Checks

Run these commands before pushing:

# Type check
yarn type-check:ci --force

# Lint and format
yarn lint:fix

# Run unit tests
TZ=UTC yarn test

# Build
yarn build

Testing Best Practices

Test Organization

packages/
├── lib/
│   ├── date/
│   │   ├── parseDate.ts
│   │   └── parseDate.test.ts
│   └── validation/
│       ├── email.ts
│       └── email.test.ts

Place test files next to the code they test for better discoverability.

Test Naming

// Good - Descriptive test names
it("should create booking when user has available time slots", () => {
  // ...
});

it("should throw error when booking conflicts with existing booking", () => {
  // ...
});

// Bad - Vague test names
it("works", () => {
  // ...
});

it("test booking", () => {
  // ...
});

Arrange-Act-Assert Pattern

it("should cancel booking and send notification", async () => {
  // Arrange
  const booking = await createTestBooking();
  const emailSpy = vi.spyOn(emailService, "send");
  
  // Act
  await cancelBooking(booking.id);
  
  // Assert
  expect(booking.status).toBe("CANCELLED");
  expect(emailSpy).toHaveBeenCalledWith({
    to: booking.attendeeEmail,
    template: "booking_cancelled",
  });
});

Test Independence

Each test should be independent:

// Good - Independent tests
describe("Booking Service", () => {
  beforeEach(() => {
    // Reset state before each test
    resetDatabase();
  });
  
  it("test 1", () => { /* ... */ });
  it("test 2", () => { /* ... */ });
});

// Bad - Tests depend on each other
describe("Booking Service", () => {
  let bookingId;
  
  it("creates booking", () => {
    bookingId = createBooking(); // Sets shared state
  });
  
  it("cancels booking", () => {
    cancelBooking(bookingId); // Depends on previous test
  });
});

Debugging Tests

Playwright Debug Mode

PLAYWRIGHT_HEADLESS=false yarn e2e

Playwright Inspector

PLAYWRIGHT_DEBUG=1 yarn e2e

Vitest Debug Mode

import { it } from "vitest";

it.only("debug this test", () => {
  // Add debugger statement
  debugger;
  // ...
});

Run with Node inspector:

node --inspect-brk ./node_modules/.bin/vitest

Testing Checklist

Before committing:

Common Testing Issues

Issue: Timezone Inconsistencies

Solution: Always set TZ=UTC when running tests:

TZ=UTC yarn test

Issue: Prisma Client Not Generated

Solution: Regenerate Prisma types:

yarn prisma generate

Issue: Playwright Browsers Not Installed

Solution: Install browsers:

npx playwright install

Issue: Port Already in Use

Solution: Kill process on port 3000:

lsof -ti:3000 | xargs kill -9

Resources

• Vitest Documentation
• Playwright Documentation
• Testing Library

Next Steps

• Review Coding Guidelines
• Explore Architecture Overview
• Set up your Development Environment