Advanced Playwright frameworks - V1, V2, upstream

V1 vs V2 - what actually changes

The folder layout is the same. The day-to-day authoring loop and the failure triage flow are different. Here is the side-by-side.

timeline
    title V1 -> V2 evolution
    section Layout
      V1 ships : POM : fixtures : env config : custom reporter : Docker : CI shards
    section AI additions
      V2 builds on V1 : AI locators : AI Page Object draft : AI trace triage : AI summary in PR
            

How the branches relate

The upstream repo carries the progression as three branches. main is the canonical layout. ttacart is the same framework wired against the TTA practice app. ttacart-ai (planned) adds the AI layer on top of ttacart.

gitGraph
    commit id: "init"
    commit id: "POM + fixtures"
    commit id: "env + reporter"
    branch ttacart
    commit id: "TTACart pages"
    commit id: "booking flow"
    commit id: "data-driven"
    branch ttacart-ai
    commit id: "AI author"
    commit id: "AI triage"
    checkout main
    commit id: "Docker + CI shards"
            

What each branch contains

• main - canonical TypeScript layout. POM, fixtures, env config, custom reporter, Docker, GitHub Actions matrix.
• ttacart - same framework, with concrete Page Objects for TTACart and the booking flow. This is the branch the V1 walkthrough mirrors.
• ttacart-ai (planned) - ttacart plus AI-assisted authoring and failure analysis. Where V2 will live.

Roadmap - the next six things

What's next on the framework side. These are the same items the V2 page tracks.

timeline
    title Roadmap - next six things
    Q1 : AI Page Object draft : trace-driven RCA
    Q2 : locator linter : DDT row suggester
    Q3 : provider adapter : budget gates
            

1. 1 AI-drafted Page Objects from screenshots. Paste a screenshot or HTML snippet, get back a typed Page Object with role-based locators. Reviewer keeps control.
2. 2 Trace-driven root-cause analysis. Feed trace.zip plus console plus network into the model. Get a hypothesis with the exact action that failed and a candidate fix.
3. 3 Locator quality linter. Static analysis that flags brittle CSS / XPath and suggests role / label / test-id replacements. Runs in pre-commit.
4. 4 Data-driven row suggester. Drop in a CSV header. Model proposes 6-10 realistic rows including edge cases (empty, max-length, unicode, locale-specific zip codes).
5. 5 Provider-pluggable model adapter. Swap between hosted models without touching framework code. One config block, one env var.
6. 6 Budget-gated AI usage. Per-repo token budget with a hard ceiling. CI fails closed if AI is unavailable or over budget - the test suite still runs without AI.

When to use V1 vs V2 vs nothing yet

The honest answer is "it depends on the size of your suite and the maturity of your test team". A small team running 20 specs does not need a framework at all - they need a tidy tests/ folder and one fixtures.ts. A team running 800 specs cannot survive without one.

Reach for nothing yet when

• You have fewer than 30 specs and a single team owns them.
• Your selectors are mostly getByRole / getByLabel already.
• Your CI runs in under 10 minutes and is rarely flaky.

Reach for V1 when

• Selectors are leaking across specs. Five tests all reference #cart-badge.
• Your CI is sequential and starting to feel slow.
• You need to run against more than one environment - qa, stg, prod.
• You want a branded report on a wiki, not the default HTML reporter.
• You have a second team about to onboard. They need a structure to read.

Reach for V2 when

• V1 is already running in your CI. AI is the next 10% improvement, not the foundation.
• You spend more than an hour a week triaging trace.zip failures.
• Authoring new Page Objects feels mechanical and slow.
• You have a token budget you are willing to spend on testing.

What you get when you clone the repo

The upstream repo follows a conventional TypeScript layout. Here is the rough folder breakdown so you know what to expect after git clone.

• src/pages/ - one Page Object per page. LoginPage, InventoryPage, CartPage, etc.
• src/fixtures/ - one or more fixture files. test-base.ts injects page objects and clients.
• src/utils/ - element wrappers, file readers, data factories, the custom Winston logger.
• src/testdata/ - JSON / CSV / XLSX fixtures plus the typed types.ts.
• src/tests/ - the actual specs, grouped by feature - login/, cart/, checkout/, booking/.
• src/api/ - ApiClient wrapping APIRequestContext.
• playwright.config.ts - one place for projects, reporters, env, timeouts.
• .env.example - template for environment-specific secrets.
• Dockerfile - reproducible test runner image based on the official Playwright image.
• .github/workflows/ - sharded CI pipeline plus the merge-reports job.
• tta-report/ - the custom HTML reporter source.

graph TB
  subgraph framework
    P[src/pages]:::pom
    F[src/fixtures]:::fix
    U[src/utils]:::utl
    D[src/testdata]:::data
    T[src/tests]:::test
    A[src/api]:::api
    C[playwright.config.ts]:::cfg
    E[.env.example]:::env
    K[Dockerfile]:::docker
    G[.github/workflows]:::ci
    R[tta-report]:::rep
  end
  T --> F
  F --> P
  F --> A
  P --> U
  T --> D
  C --> R
  G --> K
  classDef pom fill:#dcfce7,stroke:#15803d,color:#14532d;
  classDef fix fill:#fef3c7,stroke:#b45309,color:#7c2d12;
  classDef utl fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a;
  classDef data fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95;
  classDef test fill:#dcfce7,stroke:#15803d,color:#14532d;
  classDef api fill:#fef3c7,stroke:#b45309,color:#7c2d12;
  classDef cfg fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a;
  classDef env fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95;
  classDef docker fill:#fef3c7,stroke:#b45309,color:#7c2d12;
  classDef ci fill:#dcfce7,stroke:#15803d,color:#14532d;
  classDef rep fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a;
            

Quick start commands

• git clone https://github.com/PramodDutta/Advance-Playwright-Framework.git
• git checkout ttacart - switch to the TTACart-specific branch.
• npm install - installs Playwright, Faker, csv-parse, xlsx, dotenv, Winston.
• npx playwright install --with-deps - browser binaries plus OS dependencies.
• TTA_ENV=qa npx playwright test - first run against the TTA practice app.
• npx playwright show-report - opens the default HTML report.

Common questions

Do I have to use TypeScript?

The framework is TypeScript-first. You can run plain JavaScript specs - Playwright supports both - but the fixtures, types, and Page Object generics are written assuming TypeScript. If your team is JavaScript-only today, plan the TS migration as a separate exercise.

Can I run it against my own app?

Yes. Set use.baseURL in playwright.config.ts and swap the Page Objects. The ttacart branch is a worked example - main is closer to a generic starter.

Why a custom reporter when Allure exists?

Allure is excellent for trend graphs and category buckets. The custom TTA reporter exists for the case where you want a single self-contained HTML page that fits your company's brand and embeds inline thumbs without an Allure server. Use both - Allure for trends, the custom one for the report you send to a stakeholder.

Why TypeScript fixtures instead of a global setup file?

Global setup runs once per test run. Fixtures run per test (or per worker), have per-test isolation, and compose cleanly. They also show up in the trace and report as named entries. Reach for globalSetup only for truly run-once work like seeding a remote database.

What about Selenium parity?

Playwright is not Selenium. The Page Object Model translates directly, but anything that depended on JavaScript Executor, Actions chains with explicit waits, or Selenium Grid will not map one-to-one. Treat the migration as a rewrite of the test layer, not a port.

Migration paths from common starting points

Most teams that adopt V1 are not starting from zero - they have an existing Selenium suite, a flat Playwright project, or a Cypress codebase. Here is the realistic order of operations for each.

From Selenium (Java or Python)

1. Stand up a parallel Playwright project. Do not try a line-for-line port.
2. Rewrite the smoke pack first - 5 to 10 specs - using Playwright Page Objects.
3. Run both suites in CI for one or two sprints. Compare flakiness and runtime.
4. Decommission Selenium specs one feature at a time as Playwright coverage catches up.

From a flat Playwright project

1. Introduce fixtures/test-base.ts and move all setup into fixtures.
2. Extract one Page Object at a time. Start with the page touched by the most specs.
3. Replace string selectors with role-based locators along the way.
4. Add the custom reporter last - it is a quality-of-life upgrade, not a correctness fix.

From Cypress

1. The mental model is closer to Playwright than Selenium is. Most concepts translate.
2. Replace cy.intercept calls with page.route and page.waitForResponse.
3. Replace custom commands with Page Object methods or custom fixtures.
4. Multi-tab and multi-origin flows that Cypress could not handle now work natively.
5. Auto-waiting works similarly. The wait semantics are slightly different - Playwright waits per locator, Cypress retried per command. Most tests do not need any change to assertions.

One thing each migration gets wrong

• Selenium teams bring explicit waits that are no longer needed and end up with brittle waitForTimeout calls. Trust the auto-waiting.
• Flat Playwright teams over-engineer the first Page Object - constructors with five collaborators, deep inheritance. Keep it boring.
• Cypress teams miss the per-origin sandbox and underestimate how often they need cross-origin flows. That is a feature in Playwright, not a hurdle.

What to read first

• If you have never written a Playwright spec - start with Playwright fundamentals.
• If your tests work but they are messy - go through Playwright advanced.
• If you are ready for a framework - open V1 walkthrough and code along.
• If V1 already runs in your CI - try V2 + AI and see what the assistant catches that humans miss.
• If you are evaluating, just clone the repo, run npx playwright test, and judge the output.