Playwright JavaScript Framework Best Practices

Playwright JavaScript Framework Best Practices

Tópico: Playwright JavaScript Framework Best Practices
Categoria: Tutoriais | Programação & Tecnologia
Idioma Principal: Português (Conteúdo de Tecnologia)

Descrição do Conteúdo / Informações:
-------------------------------------------------------------------------
Playwright JavaScript Framework — Best Practices

A comprehensive guide for writing reliable, maintainable, and scalable end-to-end tests using Playwright with JavaScript (and Cucumber BDD) in the KeyControl test automation framework.

Table of Contents

• Project Structure & Organization

• Page Object Model (POM)

• Selectors & Locators

• Assertions

• Waiting Strategies

• Test Isolation & State Management

• Authentication & Login

• Test Data Management

• BDD / Cucumber Integration

• Error Handling & Debugging

• Retries & Flakiness

• Parallelism & Performance

• Configuration Management

• Reporting & Observability

• CI/CD Integration

• Security & Secrets

• Code Quality & Maintainability

• Accessibility & Cross-Browser Testing

1. Project Structure & Organization

DO

• Keep a flat, predictable folder structure that mirrors the application's domain (e.g., admin/, performer/, approver/, ess/).

• Co-locate feature files, step definitions, and page objects by module/domain so related code is easy to find.

• Use index.js barrel exports to avoid long relative import paths.

• Store all environment-specific configuration in a single config.js at the root; never hardcode URLs or credentials inside test files.

DON'T

• Don't scatter page objects and step definitions randomly across the project.

• Don't mix UI concerns with business logic in the same file.

Recommended Layout

features/

kc/

Admin_Group_Management_Module.feature

Performer_Task_Management_KC1.feature

step-definitions/

kc/

KeyControlAdminSteps.js

KeyControlPerformerSteps.js

page-objects/

kc/

basepage/

KeyControlAdminPage.js

KeyControlPerformerPage.js

utils/

logger.js

ExcelHelper.js

setup/

hooks.js

assertions.js

config.js

•
Page Object Model (POM)

DO

• Encapsulate all page interactions (clicks, fills, navigations) inside dedicated Page Object classes.

• Keep page objects thin — they should only expose methods, not assertions.

• Compose complex pages from smaller component objects (e.g., TableComponent, ModalComponent).

• Accept the Playwright page instance via the constructor; never create a new browser context inside a POM.
// Good — page-objects/kc/keycontrol/KeyControlAdminPage.js
export class KeyControlAdminPage {
constructor(page) {
this.page = page;

// Pre-define locators for reuse

this.groupNameInput = page.locator('[data-ga="group-name"]');

this.saveButton = page.locator('[data-ga="save-button"]');

this.successBanner = page.locator('[data-ga="success-banner"]');

}

async navigateToGroupManagement() {

await this.page.click('[data-ga="group-management"]');

}

async createGroup(groupData) {

await this.groupNameInput.fill(groupData.name);

await this.saveButton.click();

}

}

DON'T

• Don't put expect() assertions inside page objects — keep them in step definitions or test files.

• Don't duplicate selectors across multiple files; define them once in the page object.

• Selectors & Locators
Priority Order (most preferred → least preferred)
| Priority | Strategy | Example |
|---|---|---|
| 1 | data-ga / data-test attributes | [data-ga="save-button"] |
| 2 | ARIA roles & labels | page.getByRole('button', { name: 'Save' }) |
| 3 | Playwright built-in locators | page.getByLabel('Username') |
| 4 | CSS class (stable, non-generated) | .kc-modal-title |
| 5 | XPath | //div[@class="header"] |
DO

• Use data-ga or data-test attributes — they are immune to styling and structural changes.

• Use Playwright's semantic locators (getByRole, getByLabel, getByText, getByPlaceholder) for readability and resilience.

• Define locators as class properties in page objects to avoid string duplication.

• Use chaining to scope locators: page.locator('.modal').locator('[data-ga="confirm"]').
// Semantic locator
await page.getByRole('button', { name: 'Submit' }).click();

// data-ga attribute

await page.locator('[data-ga="group-name"]').fill('Automation Group');

DON'T

• Don't use auto-generated class names (div.sc-abc123) or positional XPaths (/div[3]/span[1]).

• Don't use page.$() (legacy Playwright API) — always use page.locator().

• Assertions
DO

• Always use Playwright's built-in expect — it has automatic retry, built-in timeouts, and clear error messages.

• Prefer web-first assertions that wait for the UI state to match:
// Web-first assertions (auto-retry)
await expect(page.locator('[data-ga="success-banner"]')).toBeVisible();
await expect(page.locator('[data-ga="user-count"]')).toHaveText('5');
await expect(page.locator('[data-ga="save-button"]')).toBeEnabled();

// Use soft assertions when you want to collect multiple failures in one test run:

const softExpect = expect.configure({ soft: true });

await softExpect(heading).toHaveText('Dashboard');

await softExpect(logo).toBeVisible();

// All soft assertion failures are reported at the end

DON'T

• Don't use page.isVisible() in if statements as a substitute for assertions.

• Don't hard-code waitForTimeout before an assertion — let expect do the waiting.

• Waiting Strategies
DO

• Rely on Playwright's auto-waiting — most click, fill, and expect operations auto-wait for elements to be actionable.

• Use waitForSelector or waitForResponse only for specific async operations not covered by auto-waiting.

• Wait for network responses when actions trigger API calls:
// Wait for API response after action
const [response] = await Promise.all([
page.waitForResponse(resp => resp.url().includes('/api/groups') && resp.status() === 200),
page.locator('[data-ga="save-button"]').click()
]);

// Use page.waitForLoadState('networkidle') only for pages with complex background requests.

DON'T

• Never use arbitrary page.waitForTimeout(3000) — this is a top cause of slow, flaky tests.

• Don't poll visibility in a loop; use expect(...).toBeVisible({ timeout: 10000 }) instead.

• Test Isolation & State Management
DO

• Each Cucumber scenario must be fully independent — it should not rely on state left by a previous scenario.

• Use Before / After hooks in setup/hooks.js to:

• Create a fresh browser context per scenario.

• Navigate to a known starting page.

• Clean up created test data after each scenario.
// setup/hooks.js
Before(async function () {
this.context = await browser.newContext();
this.page = await this.context.newPage();
});

After(async function (scenario) {

if (scenario.result.status === 'FAILED') {

await this.page.screenshot({ path: reports/screenshots/${scenario.pickle.name}.png });

}

await this.context.close();

});

// Use tagged hooks to apply setup only to relevant scenarios:

Before({ tags: '@admin' }, async function () {

await loginAsAdmin(this.page);

});

DON'T

• Don't share page instances or logged-in sessions across unrelated scenarios.

• Don't depend on execution order — scenarios should be runnable in any order.

• Authentication & Login
DO

• Reuse authenticated state using Playwright's storageState to avoid repeating login for every scenario:
// Save auth state once
await page.context().storageState({ path: 'setup/auth-state.json' });

// Reuse in playwright.config.js

use: {

storageState: 'setup/auth-state.json'

}

// Store credentials only in environment variables — never in code or feature files.

// Use a dedicated loginAsRole utility function to support multiple user roles cleanly.

// utils/auth.js

export async function loginAs(page, role) {

const creds = {

admin: { user: process.env.ADMIN_USER, pass: process.env.ADMIN_PASS },

performer: { user: process.env.PERFORMER_USER, pass: process.env.PERFORMER_PASS },

approver: { user: process.env.APPROVER_USER, pass: process.env.APPROVER_PASS },

ess: { user: process.env.ESS_USER, pass: process.env.ESS_PASS }

};

await page.goto(process.env.KEYCONTROL_URL);

await page.fill('[data-ga="username"]', creds[role].user);

await page.fill('[data-ga="password"]', creds[role].pass);

await page.click('[data-ga="login-button"]');

await expect(page.locator('[data-ga="dashboard"]')).toBeVisible();

}

Microsoft SSO

• See MICROSOFT_SSO_TESTING.md for handling Azure AD / Microsoft login flows.

• Mock or bypass SSO in lower environments whenever possible to speed up test execution.

• Test Data Management
DO

• Keep test data separate from test logic — store in test-data/json/ or test-data/excel/.

• Use unique data per run (e.g., timestamps, UUIDs) to prevent collisions when tests run in parallel.
const groupName = AutoGroup_${Date.now()};

// Use factory functions to generate test data objects:

// utils/dataFactory.js

export function createGroupPayload(overrides = {}) {

return {

name: AutoGroup_${Date.now()},

description: 'Generated by automation',

type: 'standard',

...overrides

};

}

// Clean up all data created during a test in the After hook.

DON'T

• Don't hardcode test data (names, IDs, dates) inside step definitions.

• Don't leave orphaned test data in shared environments — it causes noise for manual testers.

• BDD / Cucumber Integration
Feature File Best Practices

• Write scenarios from the user's perspective using Given / When / Then.

• One scenario = one behavior. Don't write "super scenarios" that test 10 things at once.

• Use Background for common pre-conditions, not complex setup logic.

• Use tags consistently to allow selective execution:
@smoke @keycontrol @admin @group-management
Feature: Admin Group Management Module

Background:

Given I am logged in as an admin

@create-group

Scenario: Admin creates a new group

When I navigate to Group Management

And I create a group with name "AutoGroup"

Then the group "AutoGroup" should appear in the list

Step Definition Best Practices

• Keep steps atomic and reusable across scenarios.

• Use World object (this) to share state between steps within a scenario — never use module-level globals.

• Avoid logic-heavy step definitions; delegate to page objects.

• Thin step, rich page object:

When('I create a group with name {string}', async function (name) {

await this.adminPage.createGroup(name);

});

•
Use Cucumber Data Tables and Doc Strings for structured input data.

• Error Handling & Debugging
DO

• Enable screenshots on failure in After hooks (see Section 6).

• Enable video recording for CI runs to replay failures:

// playwright.config.js

use: {

video: 'retain-on-failure',

screenshot: 'only-on-failure',

trace: 'retain-on-failure'

}

• Use the Playwright Trace Viewer (npx playwright show-trace trace.zip) to inspect failing steps.

• Use the built-in logger (utils/logger.js) instead of console.log for structured output.

•
Add meaningful step names so traces and reports are human-readable.

Debugging Locally

Run in headed mode with Playwright Inspector

PWDEBUG=1 npx playwright test

Run a single scenario by tag

npx test --tags="@create-group"

Slow down execution for visual debugging

npx playwright test --headed --slowmo=500

• Retries & Flakiness
Retry Policy

• Set retries: 1 (max 2) in playwright.config.js for CI — enough to handle transient network issues, not enough to hide real bugs.

• Never increase retries as a fix for a broken test — find and fix the root cause.
// playwright.config.js
retries: process.env.CI ? 1 : 0,

Flakiness Thresholds

| Level | Threshold | Action |

|---|---|---|

| Acceptable | < 1% over 7 days | Monitor |

| Warning | 1% – 5% | Investigate & RCA |

| Critical | > 5% | Block release, escalate |

Common Flakiness Causes & Fixes

| Cause | Fix |

|---|---|

| waitForTimeout | Replace with expect or waitForResponse |

| Fragile selectors | Switch to data-ga / ARIA locators |

| Shared state | Isolate each scenario (see Section 6) |

| Race conditions | Use Promise.all + network wait |

| Dynamic content | Use toBeVisible({ timeout }) instead of hard-wait |

• Parallelism & Performance
DO

• Start with workers: 2 in CI and increase only after flakiness stabilizes below 1%.

• Use Playwright sharding to distribute tests across CI runners:
npx playwright test --shard=1/3
npx playwright test --shard=2/3
npx playwright test --shard=3/3

• Group slow scenarios (e.g., approval workflows) with @slow tags and run them separately.

• Use storageState to avoid redundant logins (see Section 7).
DON'T

• Don't share a single browser context between parallel workers.

• Don't run all scenarios in parallel before verifying they are properly isolated.

• Configuration Management
DO

• Use a single config.js as the source of truth for all configuration values.

• Override config values via environment variables — never change the config file between environments.

• Use .env files for local development; inject secrets via CI environment variables in pipelines.

// config.js

export const config = {

baseUrl: process.env.KEYCONTROL_URL || 'https://qa-keycontrol.axaxl-cloud.com',

browser: process.env.BROWSER || 'edge',

headless: process.env.HEADLESS !== 'false',

defaultTimeout: Number(process.env.DEFAULT_TIMEOUT) || 120000,

actionTimeout: Number(process.env.ACTION_TIMEOUT) || 30000,

};

• See ENV_SETUP.md for full environment variable documentation.

DON'T

• Don't commit .env files with real credentials to source control.

•
Don't hardcode environment URLs in test files — always reference config.js.

• Reporting & Observability
DO

• Use Allure as the primary report for rich test history, attachments, and trend analysis.

• Attach screenshots, videos, and traces to Allure on failure automatically via hooks.

• Add Allure labels to enrich reports with metadata:

// in step definitions

this.allure.attachment('Response Body', JSON.stringify(responseBody, null, 2), 'application/json');

• Generate reports as part of every CI pipeline run:

npx run generate:report # Generate Allure report

npx run open:report # Open in browser locally

•
Maintain a weekly flakiness dashboard from Allure history data and share with the team.

Report Locations

| Type | Location |

|---|---|

| Allure HTML | allure-report/ |

| Allure Results | allure-results/ |

| JSON Report | reports/cucumber_report.json |

| Screenshots | reports/screenshots/ |

| Videos | test-results/ |

• CI/CD Integration
DO

• Run tests in headless mode in CI:

npm run test:ci

• Fail the pipeline on any test failure — don't silently ignore failed tests.

• Archive Allure results and test-results as CI artifacts for post-run analysis.

• Run linting (eslint) and type checks before executing tests in the pipeline.

•
Use branch-specific tags to run only smoke tests on PRs and full regression on main:

Example GitHub Actions step

• name: Run Smoke Tests (PR)
run: npm test -- --tags "@smoke"
if: github.event_name == 'pull_request'

• name: Run Full Suite (Main)
run: npm test
if: github.ref == 'refs/heads/main'

DON'T

• Don't run tests against production environments from CI without explicit approval gates.

• Don't skip report generation in CI — reports are essential for debugging failures.

• Security & Secrets
DO

• Store all credentials in environment variables or a secrets manager (Azure Key Vault, GitHub Secrets).

• Reference secrets via process.env.VAR_NAME — never hardcode them.

• Use .gitignore to exclude .env, auth-state.json, and any file that may contain tokens.

• Rotate test user passwords regularly and update secrets in the CI store.

• See SECRETS.md for detailed secrets management guidelines.
DON'T

• Don't log credentials or tokens to the console or report output.

• Don't commit auth-state.json (contains session tokens) to source control.

• Don't use personal accounts as test users — use dedicated service accounts.

• Code Quality & Maintainability
DO

• Enable ESLint with a consistent style guide (e.g., Airbnb or StandardJS).

• Use ES Modules (import/export) consistently — the project already uses "type": "module" in package.json.

• Use async/await everywhere — avoid mixing Promises and callbacks.

• Keep functions small and single-purpose (\le 20 lines is a good target).

• Write JSDoc comments for all page object methods and utilities.

• Review test code in pull requests — test code is production code.
/**

• Creates a new group with the given data.

•
@param {Object} groupData

•
@param {string} groupData.name

•
@param {string} [groupData.description]
*/
async createGroup(groupData) {
await this.groupNameInput.fill(groupData.name);
await this.saveButton.click();
await expect(this.successBanner).toBeVisible();
}

DON'T

• Don't leave commented-out code or console.log statements in committed code.

• Don't duplicate step definitions — extract shared steps into a common-steps.js.

• Don't use var — always use const or let.

• Accessibility & Cross-Browser Testing
Accessibility

• Prefer ARIA roles and labels as primary selectors — this naturally validates accessibility.

• Run @axe-core/playwright checks on key pages as part of accessibility regression:
import { checkA11y } from 'axe-playwright';

await checkA11y(page, undefined, {

runOnly: ['wcag2a', 'wcag2aa']

});

Cross-Browser

• The framework targets Microsoft Edge (Chromium) as the primary browser.

• Add firefox and webkit project entries in playwright.config.js for critical smoke tests when cross-browser coverage is required:

projects: [

{ name: 'edge', use: { ...devices['Desktop Edge'], channel: 'msedge' } },

{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },

{ name: 'webkit', use: { ...devices['Desktop Safari'] } }

]

• Run cross-browser tests on a schedule (e.g., nightly), not on every PR, to keep PR pipelines fast.

Quick Reference Checklist

Use this checklist before merging new tests:

• Tests are isolated — no shared state between scenarios

• data-ga or ARIA locators used — no fragile XPath/CSS

• No waitForTimeout calls

• Assertions use Playwright's expect (web-first)

• Credentials are in environment variables, not hardcoded

• Test data uses unique identifiers (timestamp/UUID)

• Screenshots/video capture is configured on failure

• Feature file has correct tags for selective execution

• Page objects contain no assertions

• Code reviewed and ESLint passes

References

• Playwright Official Documentation

• Playwright Best Practices

• Cucumber.js Documentation

• Allure Playwright Integration

• ENV_SETUP.md

• SELECTORS.md

• FLAKINESS.md

• SECRETS.md

• MICROSOFT_SSO_TESTING.md

• CI_HARNESS.md