LevelUp Playwright Framework

A production-ready Playwright + TypeScript test automation starter. It ships with a clean Page Object Model, reusable helpers, custom fixtures, multi-environment config and sensible defaults — so you (and LevelUp AI QA) can write reliable end-to-end tests from day one.

This framework is designed to be the target structure for scripts generated by LevelUp AI. When you connect this repository to LevelUp's Repo Intelligence, the AI learns your patterns (page objects, fixtures, helpers, naming) and generates new test scripts that drop straight into src/tests/ and match your existing style.

---

✨ What's inside

Area	What you get
Page Object Model	BasePage with common actions + example LoginPage / DashboardPage
Helpers	Smart waits, custom assertions, and test-data generators
Fixtures	Pre-instantiated page objects injected into every test
Config	Multi-environment (local / qa / staging) base URLs & credentials
Cross-browser	Chromium, Firefox & WebKit projects pre-configured
Reporting	HTML + list reporters, traces & screenshots on failure
Out-of-the-box tests	Smoke tests that pass immediately with npm test

---

🚀 Quick Start

1. Install

# Install dependencies
npm install

# Install the Playwright browsers (one-time)
npm run install:browsers

Requires Node.js 18+.

2. Run the tests

# Run everything (headless)
npm test

# Watch it run in a real browser
npm run test:headed

# Interactive UI mode
npm run test:ui

# Open the last HTML report
npm run report

The two "Framework smoke" tests run against playwright.dev and pass out of the box — proving your setup works before you point it at your own app.

3. Point it at your application

Open config/environments.ts (or set env vars) and update the baseURL / credentials:

# Override at runtime without editing files
BASE_URL="https://your-app.com" TEST_ENV=qa npm test

Then enable the login example: open src/tests/example.spec.ts and remove .skip from the "Login flow" tests.

---

🔗 Connect to LevelUp AI QA (recommended workflow)

This framework shines when paired with the LevelUp AI QA platform. The full loop:

Step 1 — Push this framework to GitHub

git init
git add .
git commit -m "chore: bootstrap LevelUp Playwright framework"
git branch -M main
git remote add origin https://github.com/<your-org>/<your-repo>.git
git push -u origin main

Step 2 — Connect the repo to LevelUp's Repo Intelligence

1. In the LevelUp dashboard, open Repo Intelligence and connect your GitHub repository.
2. Let it index the project. It learns your page objects, fixtures, helpers and naming conventions.
3. Optionally connect other intelligence sources (Jira, test cases, app profile) for richer context.

Step 3 — Generate scripts that match your patterns

1. Go to Script Generation in the LevelUp dashboard.
2. Click Verify Intelligence to confirm your sources are connected (repo, app profile, etc.).
3. Describe the test you want (or pick a test case). LevelUp generates a Playwright spec that:
   • extends your BasePage / uses your fixtures,
   • reuses your helpers and selectors,
   • follows your file-naming and folder structure.

Step 4 — Drop generated scripts into your suite

Save generated specs under src/tests/generated/ (create the folder), then run:

npx playwright test src/tests/generated

Because the AI was trained on this framework, the generated code imports the same test/expect fixtures and page objects — so it runs without rework.

---

📁 Folder structure

levelup-playwright-framework/
├── config/
│   └── environments.ts          # Per-env base URLs & credentials (local/qa/staging)
├── src/
│   ├── pages/
│   │   ├── BasePage.ts           # Base Page Object — common actions all pages inherit
│   │   └── examples/
│   │       ├── LoginPage.ts      # Example POM: login form
│   │       └── DashboardPage.ts  # Example POM: post-login dashboard
│   ├── helpers/
│   │   ├── waits.ts              # Network-idle / visibility / polling waits
│   │   ├── assertions.ts         # Reusable web-first assertions
│   │   └── data-generators.ts    # Random emails, usernames, people, etc.
│   ├── fixtures/
│   │   └── basePage.fixture.ts   # Custom `test` with page objects injected
│   └── tests/
│       ├── example.spec.ts       # Smoke tests (pass out of the box) + login examples
│       └── generated/            # ← put LevelUp AI-generated specs here
├── playwright.config.ts          # Projects, reporters, baseURL, traces
├── tsconfig.json                 # Strict TypeScript + path aliases
├── package.json
└── .gitignore

Path aliases

tsconfig.json defines aliases so imports stay clean as the suite grows:

import { BasePage } from '@pages/BasePage';
import { waitForNetworkIdle } from '@helpers/waits';
import { test, expect } from '@fixtures/basePage.fixture';
import env from '@config/environments';

---

🧩 How generated scripts integrate

A LevelUp-generated spec looks just like the examples — it imports your fixtures and follows your conventions:

import { test, expect } from '../fixtures/basePage.fixture';

test.describe('Employee search', () => {
  test('finds an employee by name', async ({ loginPage, dashboardPage, page }) => {
    await loginPage.open('/');
    await loginPage.login('Admin', 'admin123');
    await dashboardPage.expectLoaded();
    // ...generated steps using your page objects & helpers
  });
});

To extend the framework yourself, add a new page object under src/pages/, register it in src/fixtures/basePage.fixture.ts, and LevelUp will pick it up on the next re-index.

---

✅ Best practices baked in

• Web-first assertions (expect(locator).toBeVisible()) over manual waits — auto-retrying & flake-resistant.
• Role/label-based locators (getByRole, getByLabel) over brittle CSS/XPath where possible.
• No hard-coded sleeps — use the helpers in src/helpers/waits.ts.
• One page object per page/component, exposing intent-revealing methods (login(), not clickButton()).
• Secrets via env vars — never commit real credentials; config/environments.ts reads from process.env.
• Traces & screenshots on failure are enabled in playwright.config.ts for fast debugging (npm run report).

---

🛠️ Useful commands

Command	What it does
npm test	Run all tests headless
npm run test:headed	Run with a visible browser
npm run test:chromium	Run only the Chromium project
npm run test:ui	Playwright interactive UI mode
npm run test:debug	Step-through debugging
npm run report	Open the last HTML report
npm run typecheck	Type-check without emitting (tsc --noEmit)
npm run install:browsers	Install Playwright browser binaries

---

📚 Learn more

• Playwright docs
• Best practices
• LevelUp AI QA — Script Generation & Repo Intelligence (in your dashboard)

Happy testing! 🎭