The build plan: how to rebuild the whole framework from an empty folder

No new code today. The session opened with a checkpoint instead: share your repository in the chat, and get it to the point where the login spec runs green before Wednesday.

The reason given was not administrative. The next four topics all build on the framework existing:

There was a second instruction, repeated several times, that is worth taking literally:

That is what the rest of this page is for. It is the build plan, in the order it was taught, so the second and third rebuild do not need the videos.

The class gave the list twice, first as seven phases and then as a longer ten-step version that splits the same work more finely (page objects, fixtures and specs, utilities, test data, observability, configuration, execution, reporting and artifacts, CI, quality gates). They are the same framework. Seven is the one to memorise.

Phase 1 is a folder skeleton and nothing else. Install Node, npm init, add Playwright and TypeScript, then create the tree before writing any code:

npm init -y
npm i -D @playwright/test typescript @types/node
npx playwright install --with-deps

src/
  api/         config/      fixtures/
  pages/       testdata/    tests/       utils/

The tsconfig.json carries path aliases so specs never contain ../../..:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@api/*":      ["src/api/*"],
      "@config/*":   ["src/config/*"],
      "@fixtures/*": ["src/fixtures/*"],
      "@pages/*":    ["src/pages/*"],
      "@testdata/*": ["src/testdata/*"],
      "@utils/*":    ["src/utils/*"]
    }
  }
}

Phase 2 is playwright.config.ts plus environments. The part worth copying is the base URL resolver, because hardcoding a URL is what makes a framework single-environment forever:

function resolveBaseURL(): string {
  if (process.env.BASE_URL) return process.env.BASE_URL;
  const env = (process.env.TTA_ENV || 'qa').toLowerCase();
  switch (env) {
    case 'api':
      return process.env.API_BASE_URL || 'https://restful-booker.herokuapp.com';
    case 'dev':
    case 'local':
      return process.env.DEV_BASE_URL || 'http://localhost:3000';
    case 'stg':
    case 'staging':
      return process.env.STG_BASE_URL || 'https://stage.thetestingacademy.com';
    case 'prod':
      return process.env.PROD_BASE_URL || 'https://app.thetestingacademy.com';
    case 'qa':
    default:
      return process.env.QA_BASE_URL || 'https://app.thetestingacademy.com';
  }
}

Artifacts belong in this phase too: screenshot: 'only-on-failure', video: 'on', a trace setting, and CI-aware retries.

Utilities come before page objects, because page objects use them.

The logger is Winston, and the class made the point that you do not write this from scratch, you take createLogger from the Winston docs. What matters is the scoped child logger, so every line says where it came from:

export function createLogger(scope: string): winston.Logger {
  return logger.child({ scope });
}

2026-08-24 08:20:31 [info] [LoginPage] loginAs standard_user

Output goes to the console and to logs/combined.log, so a CI run leaves an artifact behind. That file is also what an AI agent will read later to explain a failure.

The util element locator is the wrapper every action goes through, and the Flex type is the reason it exists:

export type Flex = string | Locator;

private toLocator(target: Flex): Locator {
  return typeof target === 'string' ? this.page.locator(target) : target;
}

The data generator wraps Faker in a static class so tests import one thing. It is covered in full on the Faker and page object class, and there is a live problem with it in the repository right now, in the audit section below.

BasePage comes first, because every other page extends it. It wires three things once so no child has to:

export abstract class BasePage {
  protected readonly page: Page;
  protected readonly el: UtilElementLocator;
  protected readonly log: Logger;

  protected constructor(page: Page, scope: string) {
    this.page = page;
    this.el = new UtilElementLocator(page, scope);
    this.log = createLogger(scope);
  }

  protected async goto(relativePath: string): Promise<void> {
    await this.page.goto(relativePath);
    await this.page.waitForLoadState('domcontentloaded');
  }
}

It is abstract deliberately: there is no such thing as an instance of "a page in general", so the class should not be constructible on its own.

Phase 5 is the spec, and the spec is where assertions live. Every meaningful action goes inside a test.step with a log line, and tests carry tags:

test('logs in with valid credentials @p0', async ({ page }) => {
  await test.step('Login as standard_user', async () => {
    log.info('Logging in as standard_user');
    await loginPage.loginAs('standard_user', 'tta_secret');
  });

  await test.step('Verify login form is no longer shown', async () => {
    await expect(page.locator('[data-test="login-button"]')).toBeHidden();
  });
});

Phase 6 is reporting and quality gates. The custom reporter hangs off Playwright's reporter lifecycle. The class deferred the walkthrough to Wednesday, but the shape is worth having now, and the repository implements six hooks rather than the five mentioned live:

The quality gates named in class were ESLint for correctness, Prettier for formatting, and a type check with no ignored warnings, all run before a merge rather than after. Alongside them sits a rules/ folder of written conventions: page objects go in pages/, utilities in utils/, no console.log, no business logic in page objects, no direct locators in specs, and use the @ aliases instead of relative imports.

Phase 7 is CI and AI rules. GitHub Actions runs the suite on push and pull request and uploads the HTML report as an artifact. Jenkins is running in parallel as its own track. The AI rule files (CLAUDE.md, .cursorrules, AGENTS.md) exist so that whichever assistant a person uses, it is held to the same conventions as a human contributor.

The recap describes the finished plan. The repository is partway along it. This table is from cloning AdvancePlaywrightFramework2x, installing it and running it, not from the recap, so it doubles as your checklist.

The src/ai/ folder is further ahead than the recap suggested: rcaAgent.ts and flakyAnalyzer.ts are already there, with a providers.ts stub whose hasApiKey() returns false until a model is wired up.

All three were reproduced on a clean clone with npm install, so expect them.

One: npm test does not exist. package.json ships with "scripts": {}.

npm error Missing script: "test"

Use Playwright directly, which does work. The login spec passes in about 1.4 seconds:

npx playwright test

Worth adding to package.json on your own copy, since Phase 6 calls for it:

"scripts": {
  "test": "playwright test",
  "test:p0": "playwright test --grep @p0",
  "typecheck": "tsc --noEmit"
}

Two: DataGenerator.username() throws. This is the one to fix before Wednesday, because fixtures will lean on the data generator.

TypeError: faker.internet.userName is not a function

The file's own comment says the project pins Faker v8, but package.json asks for ^10.5.0, and the two disagree. Checked across versions: userName() exists in 8.4.1, still exists in 9.9.0 alongside the new username(), and is gone in v10. The lockfile installs 10.5.0, so the call fails.

static username(): string {
  return faker.internet.username();   // lowercase 'n' from v9 onward
}

Three: the type check fails, and Phase 1 already has the fix. TypeScript is not a dependency, so npx tsc fetches whatever is current, today 6.0.3, and exits 2:

tsconfig.json(5,25): error TS5107: Option 'moduleResolution=node10' is deprecated
tsconfig.json(13,5): error TS5101: Option 'baseUrl' is deprecated

Both come from the old-style module resolution. The module: Node16 in the build plan is exactly the modern setting that clears the first one, and aliases can be declared without baseUrl. Pin typescript in devDependencies at the same time, or your quality gate changes result depending on the day you run it.

How are tests isolated from each other? Each Playwright test gets its own browser context and page, so cookies and storage do not leak between them. Scaling that out is Docker sharding or more workers, which is a later class. The Selenium comparison raised from the floor was Chrome profiles, and the answer was that a saved profile with a logged-in user is the closest equivalent.

How do you handle a flaky locator? Not with a fixed wait. Two answers were given. The first is a locator with fallbacks, sometimes sold as "self-healing", which the class called a fancy name for something simple: try page.locator, and if that fails try getByRole, and so on down a list. The second is that waitForSelector-style waits are the vulnerable pattern in the first place, because Playwright already waits before acting.

What do you say when an interviewer asks about promises here? They are usually fishing for Promise.all and Promise.race, which were covered in the JavaScript sessions.

Why TypeScript rather than JavaScript? The argument to take to a reluctant team: scale, strictness and maintainability. Past a few thousand tests, plain JavaScript drifts into loose functions and callbacks that nobody wants to maintain, which is why the large engineering organisations moved.

Which MCPs are actually used? Jira and the Atlassian set, GitHub, Figma for diagrams, and TestRail or TestLink where a team uses them. Selenium's MCP was called not good. Many companies also run internal ones over their own QA knowledge.

Does the log file grow forever? It appends rather than overwrites, and old log files get cleaned out on a schedule, ten to fifteen days in the practice described.

Can this framework be converted? Yes to BDD, and yes to Python and Java, where the page object design carries over unchanged and only syntax and the runner change: pytest and conftest.py in place of the Playwright test runner and fixtures. A Python conversion was promised in class.

Wednesday picks up with fixtures, and the motivation given is the one that makes them click: without a fixture, every test that needs a logged-in user logs in again. A login fixture does the browser context and login once and injects the ready-made page into every test that asks for it.

After that: API testing, cucumber, and the agent factory, with Docker sharding alongside it. The custom reporter walkthrough that was deferred today also lands Wednesday.

Jenkins continues on its own track, with part 3 tonight at 9:00 PM IST running this framework's login spec on a freestyle job, and a part 4 planned to cover GitHub Actions.

• Get your repository to the login-spec baseline before Wednesday, and post the link in the batch chat. This is the prerequisite for the next four classes, not a suggestion.
• Rebuild the framework from scratch three or four times. The phases on this page are the running order.
• Fix DataGenerator.username() in your own copy while you are in there. One character.
• Jenkins part 3 tonight, 9:00 PM IST, running the advanced framework's login spec.
• Previous classes for the mechanics: scaffolding and config, BasePage, utilities and the logger, Faker and the page object model, data-driven testing.