Write and Verify Playwright Tests

Write & Verify Playwright Test

Prerequisites

Before starting, ensure Chromium is available:

cd app/client && npx playwright install chromium 2>/dev/null

Step 1 — Configure Environment

Run the configure-env.sh script to set up app/client/playwright/.env. It creates the file if missing and merges new values with any existing ones.

node .cursor/skills/write-and-verify-pw-test/scripts/configure-env.js \
  --PLAYWRIGHT_BASE_URL=https://target-dp.appsmith.com \
  --USERNAME=user@example.com \
  --PASSWORD=secret

Pass only the variables the caller provided. The script preserves existing values for anything not overridden. Supported variables:

PW_FLAG_OVERRIDES can go in .env via the script, or be passed inline when running tests (see Step 6).

Step 2 — Read Project Conventions

Before writing any spec, read these files for conventions (they are auto-applied when editing playwright/**/*.ts, but read them explicitly here):

• .cursor/rules/playwright.mdc — full conventions (POM rules, selectors, assertions, wait strategy)

Key rules to internalize:

1. Imports: import { test, expect } from "../../fixtures" (not @playwright/test)
2. Selectors: Use getByRole() > getByLabel() > getByTestId() > SELECTORS from constants. Never raw CSS.
3. No hard waits: No waitForTimeout, no networkidle. Wait for meaningful elements.
4. Auto-retrying assertions: await expect(locator).toBeVisible(), not expect(await locator.isVisible()).toBe(true)
5. Constants: API paths from playwright/constants/api-routes.ts, selectors from playwright/constants/selectors.ts, routes from playwright/constants/routes.ts. Never hardcode.
6. POMs: Constructor takes Page. No assertions in POMs. 1-5 lines per method.
7. API contract verification: Before any request.get/request.post, grep the server for the controller to confirm exact parameter names.

Step 3 — Determine Placement

Pick the tier

If the caller specifies a tier, use it. Otherwise, default to sanity.

Feature subdirectories are mandatory under sanity/ and regression/.

Decide: existing project, new project, or multiple specs

Read playwright.config.ts to understand the current projects and their setup chains.

Use an existing project when the new spec:

• Lives in a directory already covered by a project's testDir
• Doesn't need setup beyond what that project's dependency chain provides
• Example: a new widget test at tests/sanity/widgets/chart.spec.ts → use the sanity project

Create a new project when the new spec:

• Needs an expensive shared precondition not covered by existing setups (e.g., importing an app via API, connecting a specific datasource, seeding test data)
• Would slow down unrelated tests if its setup ran in a shared project
• Follow the setup/teardown/state-reader pattern from playwright.mdc (Parallelization section):
  1. Setup file in playwright/fixtures/<name>.setup.ts — performs the operation, writes state to playwright/.state/<name>.json
  2. Teardown file in playwright/fixtures/<name>.teardown.ts — cleans up
  3. State reader in playwright/helpers/<name>-state.ts — typed accessor for test files
  4. New project entry in playwright.config.ts with dependencies, testDir, and teardown

Split into multiple spec files when:

• The prompt describes multiple independent pages or concerns — one spec per page/concern
• Tests within a shared-setup project should be parallelizable — each file runs independently, reads shared state, navigates directly to its target
• A single spec would exceed ~10 tests — split by sub-feature
• Example: Git migration tests are split into migration-mysql.spec.ts, migration-postgres.spec.ts, migration-modal-form.spec.ts — all under regression/git/, all share the migration-setup project, each focused on one page

Rule of thumb: One test.describe per spec file, one concern per test(). If the prompt covers multiple concerns, prefer multiple small specs over one large one.

Step 4 — Write the Spec

Write the spec file following these patterns. Reference existing examples:

Simple spec (smoke-level):

import { test, expect } from "../../fixtures";
import { ROUTES } from "../../constants/routes";

test.describe("Smoke — Feature Name", () => {
  test("behavior description in lowercase", async ({ page }) => {
    await page.goto(ROUTES.applications);
    await expect(page.getByRole("button", { name: /new/i })).toBeVisible();
  });
});

Spec with fixture workspace/app (sanity/regression):

import { test, expect } from "../../fixtures";
import { SELECTORS } from "../../constants/selectors";

test.describe("Feature — Specific Area", () => {
  test("filters table by country", async ({ page, app }) => {
    await page.goto(app.url);
    await expect(page.locator(SELECTORS.widgetInDeployed("textwidget")).first()).toBeVisible();
    // test logic here
  });
});

If a POM is needed, create it under playwright/page-objects/ (or components/ for reusable widgets). Follow existing patterns like home.page.ts.

Step 5 — Lint Check

After writing each file, run:

cd app/client && npx eslint <spec-file-path> --ext .ts

Fix any issues before proceeding.

Step 6 — Run the Test

Auth chain (automatic — do not skip)

The config chains setup projects: signup-setup → setup → your test project. This handles fresh deployments automatically:

• signup-setup: Creates the user if needed (handles empty instance onboarding, legacy signup, and "already exists" gracefully)
• setup: Logs in and saves auth state to playwright/auth/user.json
• test project: Runs your specs with the saved auth state

This chain runs automatically when you use --project. Never bypass it by running test files directly without a project flag.