Playwright and JavaScript Test Automation Framework

Status: ✅ Hardened & Production-Ready

Features of this framework

• Design Pattern: Page Object Model — Clean separation of test logic and UI interactions
• Resilient Selectors — Prefer role-based and attribute-based locators over brittle XPath
• Reporting: Allure — Rich HTML/Allure reports with traces and screenshots
• Cloud Integration: SauceLabs — Multi-browser cloud execution support
• CI/CD-Optimized — Headless by default, artifact capture only on failure
• State-Based Waits — No hard waitForTimeout calls; all delays are deterministic

---

Getting started

Pre-requisites

• Node.js 18+ and npm 8+
• Git (recommended)
• Visual Studio Code with GitLens and Playwright Test for VSCode

Setup

# Clone and install
git clone <repo-url>cd playwright-javascript
npm install
# Verify environment
npm run sauce:check
# Run tests
npm test# Headless, all reporters
npm run test:ci # For CI pipelines
npm run e2e # E2E config variant
HEADED=true npm test# Interactive (headed) mode# Run by environment
npm run test:dev
npm run test:qa
npm run test:uat
npm run e2e:dev
npm run e2e:qa
npm run e2e:uat

---

How to write Tests

• Add new spec under e2e-tests/ folder as <feature>.spec.js
• Create or reuse a page object module in e2e-tests/page-objects/<Feature>Page.js
• Use robust selectors:getByRole(), getByLabel(), getByPlaceholder(), or stable CSS/attribute selectors
• Avoid brittle selectors: XPath with text content, CSS module class names, DOM structure dependencies
• Use state-based waits:expect(locator).toBeVisible/Enabled/Disabled(), page.waitForFunction(), never raw waitForTimeout()

Example Test

const{ test, expect }=require("@playwright/test");const{ HomePage }=require("./page-objects/HomePage");test.describe("Home Page",()=>{test.beforeEach(async({ page })=>{consthome=newHomePage(page);awaithome.navigate();});test("should display home page title",async({ page })=>{consthome=newHomePage(page);awaitexpect(page).toHaveTitle("Acme Store");});});

---

Running Tests

Local Development

npm test# Run all tests headless
HEADED=true npm test# Headed mode (watch UI)
npm run headedTest # Alias for headed mode
npx playwright test --debug # Debug mode with inspector

CI/CD Pipelines

npm run test:ci # Optimized for CI: headless=true, artifacts=on-failure
CI=true npm test# Sets CI env var for config conditions

Specific Test Files

npx playwright test e2e-tests/home.spec.js
npx playwright test e2e-tests/cart.spec.js

Reporter Options

npm run test-list-reporter # Minimal output
npm run test-line-reporter # Single-line per test
npm run test-html-reporter # Full HTML report
npm run e2e-commandline-reporter # Multiple reporters + Allure

---

Reports and Artifacts

HTML Report

npx playwright show-report # Open latest HTML report# Or navigate to: ./playwright-report/index.html

Allure Report

npm run allure-report # Generate and open Allure report
npx allure generate ./allure-results && allure open # Manual

Screenshots & Traces

• Captured in ./test-results/ on test failure
• Traces can be viewed with: npx playwright show-trace <trace-file>.zip

---

CI/CD Execution

Environment Variables

• CI=true — Triggers CI-specific config (headless, single worker, retries=2)
• HEADED=true — Forces headed mode even in CI (for debugging)
• DEBUG=pw:api — Enable Playwright debug logging
• ENV_FILE=.env.dev|.env.qa|.env.uat — Selects environment file for base URL and env-specific values

Environment Files

• .env.dev for development testing
• .env.qa for QA validation
• .env.uat for UAT validation
• .env.example as template for creating environment files

Example GitHub Actions

- name: Run testsrun: npm run test:cienv:
CI: true
- name: Upload test resultsif: failure()uses: actions/upload-artifact@v3with:
name: test-resultspath: test-results/

---

Cloud Execution: SauceLabs

Setup

1. Obtain SauceLabs credentials from https://saucelabs.com/

2. Set environment variables:

   • Windows PowerShell:$env:SAUCE_USERNAME="YOUR_USERNAME" and $env:SAUCE_ACCESS_KEY="YOUR_KEY"
   • macOS/Linux:export SAUCE_USERNAME="YOUR_USERNAME" and export SAUCE_ACCESS_KEY="YOUR_KEY"

3. Validate config:

   npm run sauce:check

Run on SauceLabs

saucectl run -c saucelabs.config.js

See SauceLabs Playwright Docs for advanced setup.

---

Best Practices

1. Selectors First: Always prefer accessibility locators (getByRole) over implementation details
2. No Magic Waits: Remove waitForTimeout(); use expect() assertions which include waits
3. POM Cleanliness: Keep page objects focused on UI interactions, not test logic
4. Parallel Testing: Leverage workers: auto in config; ensure tests are isolated
5. CI-First Config: Default settings support CI; developers opt-in to headed mode

---

Project Structure

playwright-javascript/
├── e2e-tests/
│ ├── home.spec.js # Home page test suite
│ ├── search.spec.js # Search/navigation test suite
│ ├── cart.spec.js # Cart/add-to-cart test suite
│ └── page-objects/
│ ├── HomePage.js
│ ├── SearchPage.js
│ └── CartPage.js
├── playwright.config.js # Main Playwright config
├── e2e.config.js # E2E-specific config variant
├── saucelabs.config.js # Cloud execution config
├── my-awesome-reporter.js # Custom test reporter
├── package.json
├── README.md
└── test-results/ # Test artifacts (gitignored)

---

Support & Contributions

For issues, feature requests, or improvements, please:

1. Check existing test logs in ./test-results/
2. Run npm run sauce:check to validate external config
3. Review recent changes in git history
4. Submit an issue or PR with test logs and environment details

---

Last Updated: May 2026 | Framework Version: 1.0.0 (Hardened)