34Test Automation Architecture

34.1 The two shapes of a healthy suite

34.2 Layered framework architecture

34.3 Folder structure that scales

/tests
  /e2e             # full user journeys (Playwright)
  /api             # pure HTTP chains
  /integration     # API + DB or API + UI hybrids
  /visual          # screenshot tests
  /a11y            # axe-core scans
/src
  /pages           # POM classes
  /components      # component-level page objects (shared modal, header)
  /services        # ApiClient, UserService, OrderService
  /clients         # thin: PlaywrightClient, DbClient
  /fixtures        # test.extend definitions
  /factories       # buildUser(), buildOrder() — fake data
  /utils           # helpers, custom matchers, date helpers
  /config          # env.ts, urls.ts, timeouts.ts
  /data            # static JSON, CSV fixtures
/playwright.config.ts
/tsconfig.json
/.env.example
/README.md

34.4 Patterns — which to use when

(a) Page Object Model (POM) — default

// pages/LoginPage.ts
export class LoginPage {
  constructor(private page: Page) {}
  email = () => this.page.getByLabel('Email');
  password = () => this.page.getByLabel('Password');
  signIn = () => this.page.getByRole('button', { name: 'Sign in' });
  async goto() { await this.page.goto('/login'); }
  async submit(email: string, password: string) {
    await this.email().fill(email);
    await this.password().fill(password);
    await this.signIn().click();
  }
}

(b) Screenplay pattern — for very large suites

Tests express what an Actor does using Abilities and Tasks. Heavy abstraction; pays off only in 100+ engineer / 1000+ test orgs. Overkill for most teams.

(c) App Actions — bypass UI for setup

Instead of going through the UI to set up state ("click sign-up, fill, submit, verify email…"), expose a test-only API that creates state directly. Drastically faster. Used heavily in frontend frameworks; SDETs apply it via API setup + UI verify (covered in Module 5).

34.5 Service classes — keep test code thin

// services/UserService.ts
export class UserService {
  constructor(private api: APIRequestContext) {}
  async create(data: Partial<User> = {}) {
    const payload = { ...userFactory(), ...data };
    const r = await this.api.post('/users', { data: payload });
    if (!r.ok()) throw new Error(`create failed: ${r.status()}`);
    return r.json() as Promise<User>;
  }
  async delete(id: string) {
    await this.api.delete(`/users/${id}`);
  }
}

// In a test
const user = await new UserService(request).create({ role: 'admin' });

34.6 Test data strategy

// Factory + Faker
import { faker } from '@faker-js/faker';

export function userFactory(over: Partial<User> = {}): User {
  return {
    id: faker.string.uuid(),
    name: faker.person.fullName(),
    email: faker.internet.email(),
    role: 'user',
    ...over,
  };
}

const admin = userFactory({ role: 'admin' });
const ten = Array.from({ length: 10 }, () => userFactory());

34.7 Configuration across environments

// config/env.ts
import 'dotenv/config';
import { z } from 'zod';

const Env = z.object({
  BASE_URL: z.string().url(),
  API_URL:  z.string().url(),
  ADMIN_EMAIL: z.string().email(),
  ADMIN_PASS:  z.string().min(8),
  DB_URL:   z.string(),
  CI: z.string().optional(),
});

export const env = Env.parse(process.env);
/* Fails loudly at startup if any var is missing or malformed. */

34.8 Logging and observability

• Trace + screenshot + video on retry/failure — Playwright built-in
• Structured logs from helpers — JSON lines so they're parseable by Datadog/Splunk
• JUnit XML for CI test dashboards (Bamboo, CircleCI, Jenkins)
• Allure for stakeholder-friendly reports
• Custom metrics — test runtime trend, retry rate per test, flakiness score in a time-series DB (Grafana)

34.9 Anti-patterns — what to avoid

• God Page Object — one class with 200 methods. Split by component / feature.
• Selectors in tests — never. Page objects own selectors.
• Tests depend on order — fight isolation. Each test self-sufficient.
• Shared mutable globals — last-known-state surprises. Use fixtures.
• Hardcoded URLs / users / dates — env breaks them. Factor into config + factories.
• Massive monolithic spec file — split by feature.
• Treating tests as second-class code — no review, no refactor, no rename. They rot.
• Catching errors silently — wraps masks bugs. Let them throw.

34.10 Maintenance plan (sustainable suite)

1. Weekly — review CI flake rate. Top 3 flakiest go to quarantine with a JIRA.
2. Sprintly — drop 1 quarantined test (fix or delete). Review test pyramid mix.
3. Per release — refresh storageState. Run full visual baseline regen if branding changed.
4. Quarterly — audit RTM. Drop dead tests. Re-evaluate framework upgrade.