OpenParable
Skip to content
← Back to skills

Test Frontend E2e

Testing & Quality
test-frontend-e2e

Test Frontend E2e is an Agent Skill for testing & quality published in the pwndoc/pwndoc repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Generates Playwright E2E specs for PwnDoc. Tests run against the full stack (frontend + backend + MongoDB) with pre-authenticated browser sessions. Run with ./pwndoc-cli test --frontend-e2e.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/pwndoc/pwndoc/blob/HEAD/.claude/skills/test-frontend-e2e/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/test-frontend-e2e, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Frontend E2E Test Generator

You generate Playwright E2E tests for PwnDoc. Tests run in Chromium, Firefox, and WebKit against the full application stack.

Arguments

$ARGUMENTS - The feature/flow to test (e.g., "audits", "vulnerabilities", "settings", "data-clients").

Fix Mode

If $ARGUMENTS starts with --fix, the format is:

--fix {spec-file} "{failure summary}" [--no-run]

Example: --fix frontend/tests/e2e/vulnerabilities.spec.js "Timeout waiting for selector [data-testid='vuln-row']" --no-run

In fix mode:

  1. Read the failing spec file specified in the argument
  2. Read the page source file(s) being tested (derive from the spec's routes/navigation)
  3. Read the existing E2E reference: frontend/tests/e2e/audits-list.spec.js
  4. Analyze the failure message — determine if the issue is a wrong selector, timing, test logic, or data dependency
  5. Fix the spec file using the Edit tool
  6. If --no-run is present, STOP — do not run tests. Otherwise proceed to Step 3 (Run and Fix)

Step 1: Read Source and Reference Files

Before writing any tests, ALWAYS read:

  1. The page(s) being tested: find Vue files in frontend/src/pages/ related to the feature
  2. Existing E2E reference: frontend/tests/e2e/audits-list.spec.js
  3. Playwright config: frontend/tests/playwright.config.js
  4. Auth setup: frontend/tests/e2e/auth.setup.js and frontend/tests/e2e/init-user.setup.js

Understand the page's UI elements, forms, tables, and navigation before writing selectors.

Step 2: Generate the Spec File

Write the spec to frontend/tests/e2e/{feature}.spec.js.

Authentication

Tests are pre-authenticated via setup projects. The Playwright config defines:

  1. init-user project: registers the first admin user
  2. auth-{browser} projects: logs in and saves storageState.{browser}.json
  3. {browser} projects: run *.spec.js files with saved auth state

All *.spec.js files run with authentication already handled. The test user is:

  • Username: admin, Password: Admin123, Role: admin

Test Structure

import { test, expect } from './base.js';

Important: Always import from ./base.js, NOT from @playwright/test. The base fixture auto-saves browser storage state after each test, which is required because PwnDoc rotates refresh tokens on every use. Without this, subsequent tests load stale tokens and get redirected to /login.

See template-page-spec.md for the full test scaffold.

Locator Priority (strict order)

Follow this priority strictly. Use the first one that works — do NOT skip ahead to CSS selectors.

1. getByRole() — Always try first

page.getByRole('button', { name: 'Save' })
page.getByRole('textbox', { name: 'Title' })
page.getByRole('link', { name: 'Settings' })
page.getByRole('tab', { name: 'Languages' })
page.getByRole('row').filter({ hasText: 'row content' })
page.getByRole('cell', { name: 'value' })
page.getByRole('heading', { name: 'Audits' })
page.getByRole('dialog')                        // scope modals
page.getByRole('toolbar').getByRole('listitem')  // scope toolbar

2. getByText() — Non-interactive elements

page.getByText('Vulnerability created successfully')
page.getByText(/already exists/i)

3. getByLabel() — Form controls with labels

page.getByLabel('Description')
page.getByLabel(/Name/)

4. getByPlaceholder() — Inputs with placeholder but no label

page.getByPlaceholder('Search...')

5. getByTestId() — When semantic locators don't work

page.getByTestId('delete-language-btn')

When you need getByTestId, add data-testid to the Vue source file yourself. This is preferred over CSS selectors.

6. CSS selectors — Absolute last resort Only when the element is truly outside your control and none of the above work. NEVER use Quasar CSS class selectors (.q-dialog, .q-btn, .q-card, .q-table, .q-field, or any .q-* class). These are framework implementation details that break across versions.

Scoping within dialogs/modals

// Scope to a dialog using role (NOT .q-dialog)
const dialog = page.getByRole('dialog');
await dialog.getByLabel('Title').fill('New Item');
await dialog.getByRole('button', { name: 'Create' }).click();

Chaining and filtering

// Filter rows by text content
page.getByRole('row').filter({ hasText: 'Item Name' })

// First matching element
page.getByLabel(/Name/).first()

// Narrow with .and()
page.locator('input').and(page.getByLabel('Language'))

Waiting

  • Playwright auto-waits for elements. Use expect(...).toBeVisible() rather than explicit waits.
  • For navigation: await expect(page).toHaveURL('/expected-route')
  • Never use page.waitForResponse() — assert visual outcomes instead:
    • After page.goto() or page.reload(): wait for a key UI element that only appears once data is fetched:
      await page.goto(`/audits/${auditId}/general`);
      await expect(page.getByLabel(/Name/).first()).not.toHaveValue('');
      
    • After a save action (button click or Ctrl+S): wait for the success toast:
      await page.keyboard.press('Control+s');
      await expect(page.getByText('Audit updated successfully')).toBeVisible();
      
    • After upload-triggered side-effects (images, files): assert the resulting UI element — the visual assertion implicitly waits for the async operation:
      await expect(editor.locator('img')).toBeVisible({ timeout: 5000 });
      

Multi-browser

  • Tests run in 3 browsers (Chromium, Firefox, WebKit)
  • Do NOT use browser-specific APIs
  • Use standard Playwright locators

Application Routes

RoutePageDescription
/auditsAudit ListMain dashboard
/audits/{id}Audit EditMulti-tab audit editor
/vulnerabilitiesVulnerability ListVulnerability database
/dataData ManagementOverview page
/data/customCustom DataLanguages, Audit Types, Vuln Types, Sections
/data/clientsClientsClient management
/data/companiesCompaniesCompany management
/data/templatesTemplatesReport templates
/data/collaboratorsCollaboratorsCollaborator management
/data/spellcheckSpellcheckSpellcheck dictionary
/data/languagetool-rulesLanguageTool RulesGrammar rules
/settingsSettingsApplication settings, backups
/profileUser ProfileProfile management

Step 3: Run and Fix

If $ARGUMENTS contains --no-run, STOP HERE. Do not run tests — the calling orchestrator will handle test execution. Strip --no-run from arguments before processing the feature name in earlier steps.

Otherwise, run tests with:

./pwndoc-cli test --frontend-e2e

Do not combine E2E runs with --coverage; coverage mode only supports backend and frontend unit suites.

If tests fail, read the error output, fix the spec, and re-run. Iterate until all tests pass across all browsers.

Reference

See template-page-spec.md for a complete scaffold.