CITApp Playwright testing: from repeated actions to reusable workflows

AI-SAI-Generated Summary H-RHuman Reviewed H-EHuman Edited

I needed an E2E testing suite that could support several TOL web applications, including legacy applications whose frontend I often could not change. I started by recording browser interactions, then moved repeated work into shared functions. Tests could describe a workflow while those functions handled the application’s controls, labels, and navigation.

That foundation supported more than test maintenance. Documented helpers gave agents a vocabulary for drafting and repairing tests. User stories, readable test steps, and named screenshots also supplied material for user-manual drafts.

When the work happened

I began using Playwright for E2E automation on another application in mid-2024. This project began in early 2025, with much of the Claude and agent work taking place from early 2025 through December 2025. The general timeline places the stages in that window; individual milestone months remain approximate.

Follow the progression

The walkthrough starts with repeated browser actions, explains the shared functions in detail, and returns to those functions when following generated tests and documentation. Code examples are visible on the page as fenced, syntax-highlighted blocks. The helper chapters show complete implementations and larger call examples with their setup and configuration.

Chapter	What it explains
Suite evolution	Recorded actions, function-based POM principles, shared setup, and common values.
Helper files and configuration	Where application workflows, components, data, and execution reporting live.
Functions explained	A guide to the four detailed helper walkthroughs below.
Email template helpers	Common template interactions, optional sections, reminders, iframe cells, and complete inline/JSON examples.
Address helpers	Primary and mailing forms, the original and configurable implementations, and complete inline/JSON examples.
Named screenshots	Capture implementation, test lifecycle, filenames, documentation destinations, and a manual image reference.
Selector diagnostics	logAllBoxes, enhanced output, failure hooks, and an example of investigating a selector change.
Docs as code	How helper source became a developer reference, including Sphinx presentation and deprecation.
Agent workflow	Recordings → stories → helper-based tests → execution feedback and repairs.
Complete Proof of Address test	A complete spec with its imports, shared lifecycle, calls, and outputs explained.
User-manual drafts	How stories, test steps, configuration, and images became material for a reviewed manual draft.

What the abstraction made possible

The email-template functions are a small example of the design. Several applications handled templates in similar ways, so the test could name a template and its differences. The email walkthrough shows all three implementations and the complete test around calls like these:

// Illustrative calls: page is authenticated and at the template screen.
await verifyTemplateFields(page, 'Welcome Email', {
    hasHelperTags: true,
    hasNotice: false
});
await setReminderHours(page, 'Reminder Settings', {
    first: '24',
    second: '48',
    afterSecond: '72'
});
await interactWithIframeCell(page, 'Email Body');

When a common control changed, its helper supplied one place to investigate and repair the interaction. When values differed, arguments or configuration supplied those values. Application-specific behavior still needed the appropriate navigation, login, and component implementation.

The same division carried into the final feature tests: setup established the starting screen, workflow helpers performed actions, configuration supplied expected labels, and screenshot utilities named the resulting images.

        flowchart TD
    S[Readable test specification] --> H[Setup and login harness]
    S --> D[Application workflow helpers]
    S --> C[Component and verification helpers]
    V[Shared values and application configuration] --> D
    V --> C
    H --> B[Existing application in the browser]
    D --> C
    C --> B
    S --> A[Named test and documentation screenshots]
    A --> M[User-manual drafts and author review]
    R[Runner and reporters] --> E[Execution results and diagnostics]
    E --> F[Agent investigation and rerun]
    F --> S
    D --> J[Generated helper reference]
    C --> J
    

The implementation applies POM principles through functions and modules that encapsulate page behavior. The source examples show that organization directly. They also preserve limitations such as fixed waits, fallback selectors, and helpers that log a missing condition instead of asserting it.

From shared helpers to agents and manuals

Once the common operations had names and documentation, an agent could consult them when converting a recording into a test. The agent chapter follows CIT Corporations through a recording, summary, refined story, and final spec, referring back to the helper chapters for implementation details.

The Proof of Address walkthrough then shows a complete spec. Its screenshot calls connect directly to the naming and destination rules explained in named screenshots. The manual chapter follows those assets into proposed procedures and draft pages.

I generally began selector investigations with test output and diagnostic helpers, and eventually also used Playwright MCP for interactive investigation. The diagnostics chapter explains how I used both approaches.

• General project timeline
  • Working timeline
• From recorded actions to a reusable testing language
  • 1. The application constraints
  • 2. A recording as the starting point
  • 3. POM principles in a function-based implementation
  • 4. Centralize setup and recurring UI difficulties
  • 5. Expand the shared vocabulary without erasing application differences
  • 6. Move common values out of individual scenarios
  • 7. JSON helper references as context for agents
• Helper files, application behavior, and configuration
  • The module layout
  • cit-app-helpers.ts: application-level operations
  • cit-app-config.ts: expectations outside the test body
  • console-reporter.ts: making execution inspectable
  • Bring the parts together
• Functions explained: reusable workflows and diagnostics
  • Email templates: handle a recurring pattern once
  • Primary and mailing addresses: one call for a repeated form
  • takeNamedScreenshot: give images a reusable identity
  • Diagnostic functions: give the agent evidence about selectors
• Email template helpers: keeping repeated interactions out of tests
  • Open a template and handle its optional sections
  • Fill reminders within the correct region
  • Reach a cell inside the email iframe
  • A complete test with inline values
  • The same workflow with JSON configuration
  • Where this helper fits in the larger suite
• Primary and mailing addresses: one workflow, several helper generations
  • The original operation behind the short call
  • Accept address data without changing the scenario’s purpose
  • A complete test with inline address values
  • The same call with JSON configuration
  • Reuse this explanation later
• Named screenshots: from a test step to a manual image
  • How the capture gets its filename
  • A complete workflow that produces meaningful image names
  • Or keep screenshot labels in JSON
  • Route a capture to a documentation section
  • Put the reviewed image into a manual
• Selector diagnostics: giving the agent evidence from a failed test
  • What the original logAllBoxes collected
  • What the enhanced version added
  • Connect the output to the failure
  • A complete example using the correct page
  • Use the evidence to repair the shared operation
  • Logs first, with later Playwright MCP use
• Explaining the docs-as-code architecture
  • 1. The documentation layout
  • 2. A function and its reference page
  • 3. The Markdown and build configuration
  • 4. Local sphinx-js presentation
  • 5. Deprecation and API maintenance
  • 6. A reference for developers and agents
• From reusable helpers to an agent-assisted workflow
  • Give the agent a vocabulary it can reuse
  • Raw codegen as input
  • CIT Corporations across the artifacts
  • From recording to readable stories
  • A refined story connects tests and documentation
  • The final test vocabulary
  • Add an agent repair loop
  • What I wanted to improve
• Full example: Account → Proof of Address
  • The complete file
  • What the imports contribute
  • The lifecycle, step by step
  • What each step does
  • How the screenshots become useful outside testing
  • Readability and assertion behavior
• From user stories and tests to a rough user manual
  • The inputs working together
  • Connect a story to its test
  • What the documentation generator assembled
  • A rough manual section from the tested workflow
  • How this supported different manuals