CDAT Pattern

Test architecture for Playwright.
Battle-tested across 9 production systems over 2 years.

4 layers · 3 zero-rules · MIT licensed

Quickstart → View on GitHub ↗ Read deep dive →

0 production systems
0 months in production
0 hardcoded waits

Three Zero Rules

Three bright lines that keep tests reliable, readable, and maintainable. Toggle each card to compare bad versus good code.

Zero any

Type Safety Without Compromise

TypeScript any defeats the entire purpose of type checking. ESLint rule @typescript-eslint/no-explicit-any enforced. Every function signature must specify its return type. Generics over any, always.

async getProductData(): Promise<any> {
  const data = await fetchJson('/api/product');
  return data;
}

interface ProductData {
  id: string;
  price: number;
  name: string;
}

async getProductData(): Promise<ProductData> {
  return fetchJson<ProductData>('/api/product');
}

Zero waitForTimeout

Smart Waits Only

Hardcoded delays are flaky and slow. They fail on slow CI, succeed on fast dev machines, and waste time when elements load fast. Smart waits target the actual condition, not arbitrary time.

await page.waitForTimeout(5000);
await button.click();

await Cdat.waitAndClick(button);

Zero else

Early Returns Over Pyramids

Nested if-else creates pyramids of indentation that obscure logic flow. Early returns flatten the code, making each precondition explicit and the happy path obvious.

if (user.isValid) {
  if (user.hasPermission) {
    processOrder(user);
  } else {
    throw new Error('No permission');
  }
} else {
  throw new Error('Invalid user');
}

if (!user.isValid) throw new Error('Invalid user');
if (!user.hasPermission) throw new Error('No permission');
processOrder(user);

See the 4 layers in real code

A working login feature, exactly as it lives in the cdat-pattern repository. Switch tabs, copy code, drop it into your project.

/**
 * Login Feature - Components Layer
 *
 * This file contains ONLY locators and selectors.
 * No business logic, no assertions, no waits.
 *
 * @layer Components (C in CDAT)
 */

import type { Page, Locator } from '@playwright/test';

/**
 * Login page component locators
 *
 * @example
 * ```typescript
 * const components = new LoginComponents(page);
 * await components.usernameInput.fill('user');
 * ```
 */
export class LoginComponents {
  // ─────────────────────────────────────────────────────────────────
  // FORM ELEMENTS
  // ─────────────────────────────────────────────────────────────────

  /** Username/email input field */
  readonly usernameInput: Locator;

  /** Password input field */
  readonly passwordInput: Locator;

  /** Submit/login button */
  readonly submitButton: Locator;

  // ─────────────────────────────────────────────────────────────────
  // FEEDBACK ELEMENTS
  // ─────────────────────────────────────────────────────────────────

  /** Error message container */
  readonly errorMessage: Locator;

  /** Success message or redirect indicator */
  readonly successIndicator: Locator;

  // ─────────────────────────────────────────────────────────────────
  // NAVIGATION ELEMENTS
  // ─────────────────────────────────────────────────────────────────

  /** Forgot password link */
  readonly forgotPasswordLink: Locator;

  /** Register/Sign up link */
  readonly registerLink: Locator;

  /** Remember me checkbox */
  readonly rememberMeCheckbox: Locator;

  constructor(private readonly page: Page) {
    // Form elements
    this.usernameInput = page.getByLabel('Username');
    this.passwordInput = page.getByLabel('Password');
    this.submitButton = page.getByRole('button', { name: 'Sign in' });

    // Feedback elements
    this.errorMessage = page.locator('[data-testid="error-message"]');
    this.successIndicator = page.locator('[data-testid="success-indicator"]');

    // Navigation elements
    this.forgotPasswordLink = page.getByRole('link', { name: /forgot password/i });
    this.registerLink = page.getByRole('link', { name: /sign up|register/i });
    this.rememberMeCheckbox = page.getByLabel(/remember me/i);
  }

  // ─────────────────────────────────────────────────────────────────
  // COMPOSED SELECTORS (Selector Composition Pattern)
  // ─────────────────────────────────────────────────────────────────

  /**
   * Get a specific field error by field name
   *
   * @param fieldName - Name of the field (username, password)
   * @returns Locator for the field-specific error message
   */
  getFieldError(fieldName: string): Locator {
    return this.page.locator(`[data-testid="${fieldName}-error"]`);
  }
}

/**
 * Login Feature - Data Layer
 *
 * This file contains ONLY test data, types, and constants.
 * No business logic, no locators.
 *
 * @layer Data (D in CDAT)
 */

// ─────────────────────────────────────────────────────────────────
// INTERFACES
// ─────────────────────────────────────────────────────────────────

/**
 * User credentials for login
 */
export interface LoginCredentials {
  username: string;
  password: string;
  rememberMe?: boolean;
}

/**
 * Login response data
 */
export interface LoginResult {
  success: boolean;
  errorMessage?: string;
  redirectUrl?: string;
}

// ─────────────────────────────────────────────────────────────────
// ENUMS
// ─────────────────────────────────────────────────────────────────

/**
 * Types of login errors
 */
export enum LoginErrorType {
  InvalidCredentials = 'Invalid username or password',
  AccountLocked = 'Account is locked',
  AccountDisabled = 'Account is disabled',
  NetworkError = 'Network error occurred',
  RequiredField = 'This field is required',
}

// ─────────────────────────────────────────────────────────────────
// TEST DATA - Valid Credentials
// ─────────────────────────────────────────────────────────────────

/**
 * Valid test user credentials
 * Works with demo.playwright.dev/todoapp
 */
export const VALID_USER: LoginCredentials = {
  username: 'testuser',
  password: 'Password123!',
  rememberMe: false,
};

/**
 * Admin user credentials
 */
export const ADMIN_USER: LoginCredentials = {
  username: 'admin',
  password: 'AdminPass123!',
  rememberMe: true,
};

// ─────────────────────────────────────────────────────────────────
// TEST DATA - Invalid Credentials
// ─────────────────────────────────────────────────────────────────

/**
 * Invalid credentials for negative testing
 */
export const INVALID_CREDENTIALS: LoginCredentials = {
  username: 'wronguser',
  password: 'wrongpassword',
};

/**
 * Empty credentials for validation testing
 */
export const EMPTY_CREDENTIALS: LoginCredentials = {
  username: '',
  password: '',
};

/**
 * Credentials with SQL injection attempt (for security testing)
 */
export const SQL_INJECTION_ATTEMPT: LoginCredentials = {
  username: "' OR '1'='1",
  password: "' OR '1'='1",
};

// ─────────────────────────────────────────────────────────────────
// URLS
// ─────────────────────────────────────────────────────────────────

/**
 * URL paths for login feature
 */
export const LOGIN_URLS = {
  loginPage: '/login',
  dashboardPage: '/dashboard',
  forgotPasswordPage: '/forgot-password',
  registerPage: '/register',
} as const;

// ─────────────────────────────────────────────────────────────────
// TIMEOUTS
// ─────────────────────────────────────────────────────────────────

/**
 * Feature-specific timeout overrides
 */
export const LOGIN_TIMEOUTS = {
  /** Time to wait for login API response */
  loginApiResponse: 10000,
  /** Time to wait for redirect after successful login */
  redirectAfterLogin: 5000,
} as const;

/**
 * Login Feature - Actions Layer
 *
 * This file contains business logic and user interactions.
 * NO expect() assertions here - those belong in tests.
 *
 * @layer Actions (A in CDAT)
 */

import type { Page } from '@playwright/test';
import { Cdat, LocatorState } from '../../utils/Cdat';
import { LoginComponents } from './components';
import type { LoginCredentials, LoginResult } from './data';

/**
 * Login feature actions
 *
 * Implements user interactions for login functionality.
 * All methods use smart waits (Zero waitForTimeout principle).
 *
 * @example
 * ```typescript
 * const actions = new LoginActions(page);
 * await actions.login(VALID_USER);
 * ```
 */
export class LoginActions {
  private readonly components: LoginComponents;

  constructor(private readonly page: Page) {
    this.components = new LoginComponents(page);
  }

  // ─────────────────────────────────────────────────────────────────
  // ATOMIC ACTIONS (Single Responsibility)
  // ─────────────────────────────────────────────────────────────────

  /**
   * Fill username field
   *
   * @param username - Username to enter
   */
  async fillUsername(username: string): Promise<void> {
    await Cdat.waitAndFill(this.components.usernameInput, username);
  }

  /**
   * Fill password field
   *
   * @param password - Password to enter
   */
  async fillPassword(password: string): Promise<void> {
    await Cdat.waitAndFill(this.components.passwordInput, password);
  }

  /**
   * Click submit button
   */
  async clickSubmit(): Promise<void> {
    await Cdat.waitAndClick(this.components.submitButton);
  }

  /**
   * Toggle remember me checkbox
   *
   * @param checked - Whether to check the checkbox
   */
  async setRememberMe(checked: boolean): Promise<void> {
    if (checked) {
      await Cdat.waitAndCheck(this.components.rememberMeCheckbox);
      return;
    }

    await Cdat.waitAndUncheck(this.components.rememberMeCheckbox);
  }

  // ─────────────────────────────────────────────────────────────────
  // COMPOSED ACTIONS (Method Composition Pattern)
  // ─────────────────────────────────────────────────────────────────

  /**
   * Perform complete login flow
   *
   * @param credentials - User credentials
   *
   * @example
   * ```typescript
   * await actions.login({ username: 'user', password: 'pass' });
   * ```
   */
  async login(credentials: LoginCredentials): Promise<void> {
    await this.fillUsername(credentials.username);
    await this.fillPassword(credentials.password);

    if (credentials.rememberMe !== undefined) {
      await this.setRememberMe(credentials.rememberMe);
    }

    await this.clickSubmit();
  }

  /**
   * Login and wait for successful redirect
   *
   * @param credentials - User credentials
   * @param expectedUrl - Expected URL after successful login
   */
  async loginAndWaitForRedirect(
    credentials: LoginCredentials,
    expectedUrl: string
  ): Promise<void> {
    await this.login(credentials);
    await Cdat.waitForUrlContains(this.page, expectedUrl);
  }

  // ─────────────────────────────────────────────────────────────────
  // STATE GETTERS (No assertions - return data for tests)
  // ─────────────────────────────────────────────────────────────────

  /**
   * Get current error message text
   *
   * @returns Error message text or empty string if not visible
   */
  async getErrorMessage(): Promise<string> {
    const isVisible = await Cdat.checkState(
      this.components.errorMessage,
      LocatorState.Visible
    );

    if (!isVisible) {
      return '';
    }

    return Cdat.waitForText(this.components.errorMessage);
  }

  /**
   * Check if login was successful (success indicator visible)
   *
   * @returns true if success indicator is visible
   */
  async isLoginSuccessful(): Promise<boolean> {
    return Cdat.checkState(
      this.components.successIndicator,
      LocatorState.Visible
    );
  }

  /**
   * Check if error message is displayed
   *
   * @returns true if error message is visible
   */
  async isErrorDisplayed(): Promise<boolean> {
    return Cdat.checkState(
      this.components.errorMessage,
      LocatorState.Visible
    );
  }

  // ─────────────────────────────────────────────────────────────────
  // NAVIGATION ACTIONS
  // ─────────────────────────────────────────────────────────────────

  /**
   * Navigate to login page
   *
   * @param baseUrl - Base URL of the application
   */
  async navigateToLoginPage(baseUrl: string): Promise<void> {
    await this.page.goto(`${baseUrl}/login`);
  }

  /**
   * Click forgot password link
   */
  async clickForgotPassword(): Promise<void> {
    await Cdat.waitAndClick(this.components.forgotPasswordLink);
  }

  /**
   * Click register link
   */
  async clickRegister(): Promise<void> {
    await Cdat.waitAndClick(this.components.registerLink);
  }

  // ─────────────────────────────────────────────────────────────────
  // FORM HELPERS
  // ─────────────────────────────────────────────────────────────────

  /**
   * Clear all form fields
   */
  async clearForm(): Promise<void> {
    await Cdat.waitAndClear(this.components.usernameInput);
    await Cdat.waitAndClear(this.components.passwordInput);
  }

  /**
   * Get current form values
   *
   * @returns Current values in the form
   */
  async getFormValues(): Promise<{ username: string; password: string }> {
    const username = await Cdat.waitForInputValue(this.components.usernameInput);
    const password = await Cdat.waitForInputValue(this.components.passwordInput);

    return { username, password };
  }
}

/**
 * Login Feature - Tests Layer
 *
 * This file contains test scenarios with assertions.
 * All expect() calls belong HERE, not in Actions.
 *
 * @layer Tests (T in CDAT)
 */

import { test, expect } from '@playwright/test';
import { LoginActions } from './actions';
import { LoginComponents } from './components';
import {
  VALID_USER,
  INVALID_CREDENTIALS,
  EMPTY_CREDENTIALS,
  LOGIN_URLS,
  LoginErrorType,
} from './data';

// ─────────────────────────────────────────────────────────────────
// TEST SETUP
// ─────────────────────────────────────────────────────────────────

test.describe('Login Feature', () => {
  let actions: LoginActions;
  let components: LoginComponents;

  test.beforeEach(async ({ page, baseURL }) => {
    actions = new LoginActions(page);
    components = new LoginComponents(page);

    // Navigate to login page before each test
    await page.goto(`${baseURL}${LOGIN_URLS.loginPage}`);
  });

  // ─────────────────────────────────────────────────────────────────
  // POSITIVE SCENARIOS
  // ─────────────────────────────────────────────────────────────────

  test.describe('Positive Scenarios', () => {
    test('TC_LOGIN_001: Given valid credentials, When user logs in, Then dashboard is displayed', async ({
      page,
    }) => {
      // Arrange
      const credentials = VALID_USER;

      // Act
      await actions.login(credentials);

      // Assert
      await expect(page).toHaveURL(new RegExp(LOGIN_URLS.dashboardPage));
    });

    test('TC_LOGIN_002: Given valid credentials with remember me, When user logs in, Then session persists', async ({
      page,
    }) => {
      // Arrange
      const credentials = { ...VALID_USER, rememberMe: true };

      // Act
      await actions.login(credentials);

      // Assert
      await expect(page).toHaveURL(new RegExp(LOGIN_URLS.dashboardPage));
      // Additional assertion: Check for persistent session cookie
      const cookies = await page.context().cookies();
      const sessionCookie = cookies.find((c) => c.name === 'session');
      expect(sessionCookie?.expires).toBeGreaterThan(Date.now() / 1000);
    });
  });

  // ─────────────────────────────────────────────────────────────────
  // NEGATIVE SCENARIOS
  // ─────────────────────────────────────────────────────────────────

  test.describe('Negative Scenarios', () => {
    test('TC_LOGIN_003: Given invalid credentials, When user logs in, Then error is displayed', async () => {
      // Arrange
      const credentials = INVALID_CREDENTIALS;

      // Act
      await actions.login(credentials);

      // Assert
      const errorMessage = await actions.getErrorMessage();
      expect(errorMessage).toContain(LoginErrorType.InvalidCredentials);
    });

    test('TC_LOGIN_004: Given empty username, When user submits form, Then validation error is shown', async () => {
      // Arrange
      const credentials = { ...EMPTY_CREDENTIALS, password: 'somepassword' };

      // Act
      await actions.login(credentials);

      // Assert
      const fieldError = components.getFieldError('username');
      await expect(fieldError).toBeVisible();
      await expect(fieldError).toContainText(LoginErrorType.RequiredField);
    });

    test('TC_LOGIN_005: Given empty password, When user submits form, Then validation error is shown', async () => {
      // Arrange
      const credentials = { ...EMPTY_CREDENTIALS, username: 'someuser' };

      // Act
      await actions.login(credentials);

      // Assert
      const fieldError = components.getFieldError('password');
      await expect(fieldError).toBeVisible();
      await expect(fieldError).toContainText(LoginErrorType.RequiredField);
    });
  });

  // ─────────────────────────────────────────────────────────────────
  // NAVIGATION SCENARIOS
  // ─────────────────────────────────────────────────────────────────

  test.describe('Navigation', () => {
    test('TC_LOGIN_006: Given login page, When forgot password clicked, Then forgot password page opens', async ({
      page,
    }) => {
      // Act
      await actions.clickForgotPassword();

      // Assert
      await expect(page).toHaveURL(new RegExp(LOGIN_URLS.forgotPasswordPage));
    });

    test('TC_LOGIN_007: Given login page, When register clicked, Then register page opens', async ({
      page,
    }) => {
      // Act
      await actions.clickRegister();

      // Assert
      await expect(page).toHaveURL(new RegExp(LOGIN_URLS.registerPage));
    });
  });

  // ─────────────────────────────────────────────────────────────────
  // ACCESSIBILITY SCENARIOS
  // ─────────────────────────────────────────────────────────────────

  test.describe('Accessibility', () => {
    test('TC_LOGIN_008: Given login form, Then all inputs have accessible labels', async () => {
      // Assert
      await expect(components.usernameInput).toBeVisible();
      await expect(components.passwordInput).toBeVisible();

      // Verify labels are properly associated
      await expect(components.usernameInput).toHaveAccessibleName(/username/i);
      await expect(components.passwordInput).toHaveAccessibleName(/password/i);
    });

    test('TC_LOGIN_009: Given login form, Then form is keyboard navigable', async ({ page }) => {
      // Act - Navigate with Tab key
      await page.keyboard.press('Tab');
      await page.keyboard.press('Tab');
      await page.keyboard.press('Tab');

      // Assert - Submit button should be focused
      await expect(components.submitButton).toBeFocused();
    });
  });
});

Why split into 4 files?

Separation of concerns - locators, data, behavior, and assertions never share a file.
Dependency direction - Components and Data have zero dependencies; Actions consume both; Tests consume all three.
Reusability - Actions can compose other Actions, locators can be shared, data fixtures stay typed.

CDAT vs Classic POM vs Screenplay

Apples-to-apples on the seven decisions that matter.

Aspect	Classic POM	Screenplay	CDAT
Organization	Per page	Per actor	Per feature (vertical slice)
Layers	Mixed (1-2)	5+ (Actor, Task, Question, Ability, Interaction)	4 separated (C/D/A/T)
Locators home	Page Object class	Targets module	components.ts (dedicated)
Test data	Hardcoded in tests	Question objects	data.ts (typed)
Assertions	Often in PO	Tasks may contain	Only in test.ts
Learning curve	Low	Steep	Gentle
Best for	Small projects	Enterprise BDD	Any project size

Learn more in /docs/architecture →

9 production systems. 2 years. Zero regrets.

CDAT has shipped tests across nine domains. Categories below are the pattern's home turf - anonymized, but real.

🏢
B2B Platform A
- 12K LOC
- 340 tests
- 24 months
🛒
E-commerce 1
- 18K LOC
- 520 tests
- 9 months
📇
CRM Application
- 9K LOC
- 280 tests
- 23 months
📅
Event Management
- 7K LOC
- 210 tests
- 19 months
🎓
Education Platform
- 11K LOC
- 350 tests
- 18 months
🧾
Invoicing System
- 6K LOC
- 180 tests
- 24 months
🚚
Logistics App
- 14K LOC
- 410 tests
- 11 months
🚗
Automotive Wholesale
- 13K LOC
- 380 tests
- 22 months
🏛️
B2B Platform B
- 10K LOC
- 300 tests
- 21 months

CDAT Pattern

Why split into 4 files?

B2B Platform A

E-commerce 1

CRM Application

Event Management

Education Platform

Invoicing System

Logistics App

Automotive Wholesale

B2B Platform B