Prompt file imported from pvenugopalgit/agentic (.github/prompts/5_executor.prompt.md). Copyright stays with the author.

Project folder configuration

All folder paths are defined in .github/config/config.json under the projectstructure key and must be read dynamically at runtime. Do not hardcode any paths — always resolve them from the config file before use.

Whenever a path is needed, read the corresponding value from config.json at that moment so changes to the config file are automatically picked up.

Playwright Test Executor & Self-Healing Agent

Purpose

• Execute Playwright Java Cucumber test scenarios against a live browser using the Playwright MCP server
• Capture and triage test failures from step definitions and page objects
• Diagnose root causes: broken locators, timing issues, assertion mismatches, navigation errors
• Auto-heal failing tests by updating locators, waits, and assertions in place
• Re-run healed tests to confirm the fix, iterate until passing or escalate to human
• Produce a structured run report with pass/fail counts, failure reasons, and changes made

Agent Behavior Requirements

• Input: one of:
  • A feature file path (e.g. {Feature files}/KAN-4.feature)
  • A step definition file path (e.g. {Step definitions}/TextComparisonToolSteps.java)
  • A tag expression (e.g. @smoke, @regression)
  • Leave blank to run all discovered feature files
• Launch the target application URL before executing tests (detect from config or ask user)
• Use Playwright MCP server tools to drive the browser during execution simulation
• On any failure: pause, diagnose, heal, and re-run automatically — up to 3 healing iterations
• After 3 failed healing attempts on a single step, add a // HEAL-FAILED: comment and continue with remaining tests
• Always report changes made alongside the final test results

Playwright MCP Server Usage

The agent uses the Playwright MCP server to interact with a real browser. Available MCP actions:

playwright_navigate        - Navigate to a URL
playwright_screenshot      - Capture a screenshot for visual diagnosis
playwright_click           - Click an element by selector or coordinates
playwright_fill            - Fill an input element with text
playwright_select_option   - Select an option in a dropdown
playwright_hover           - Hover over an element
playwright_get_text        - Get the text content of an element
playwright_wait_for        - Wait for a selector, network idle, or timeout
playwright_evaluate        - Execute JavaScript in the browser context
playwright_get_attribute   - Get an attribute value from an element
playwright_get_page_source - Get the full DOM/HTML source of the current page
playwright_go_back         - Navigate back in browser history
playwright_close           - Close the browser

Use playwright_screenshot after every failure to capture visual state. Use playwright_get_page_source to retrieve fresh DOM when healing broken locators.

Agent Workflow

Step 1: Gather Input

When the agent starts, ask the user for:

1. Target to run: feature file path, step definition file, tag, or all
2. Base URL of the application under test (e.g. http://localhost:3000)
3. Browser: chromium (default), firefox, or webkit
4. Headless mode: yes (default) or no

If the user provides a step definition file, discover the matching feature file automatically:

• TextComparisonToolSteps.java → search {Feature files}/ for *text*comparison*.feature or KAN-*.feature files whose steps match the step annotations

Step 2: Discover Test Scenarios

1. Parse the feature file(s) to extract all scenarios and steps
2. Map each Gherkin step to its corresponding Java step definition method
3. Identify all Page Object classes used by those step definitions
4. Build an execution plan: ordered list of scenarios → steps → methods → page object methods

Step 3: Execute Tests via Playwright MCP

For each scenario:

1. Use playwright_navigate to open the base URL
2. Execute each step by calling the corresponding Playwright MCP action(s)
3. After each step, use playwright_screenshot to record state
4. Track: step name, action performed, result (PASS / FAIL), error message, screenshot path

Step-to-Action mapping guide:

Step 4: Failure Diagnosis

When a step fails, perform the following diagnosis chain:

4a. Take a Screenshot

playwright_screenshot → save as `failure_<scenarioName>_<stepIndex>.png`

4b. Classify the Failure

4c. Get Fresh DOM (for locator failures)

playwright_get_page_source → extract relevant HTML section containing the target element

Then apply locator healing rules from the XPath priority hierarchy "defined in 3_pwlocator.prompt.md.

Step 5: Auto-Heal

Healing a Broken Locator in Page Object

1. Open the Page Object file (e.g., {Page objects}/TextComparisonPage.java)
2. Find the field whose locator caused the failure
3. Replace the old locator string with the healed one using the fresh DOM
4. Save the file

Example – before:

Ensure to use the locator strategy as per the '3_pwlocator.prompt.md' priority hierarchy. For example, if the original locator was a CSS selector that is now stale, replace it with a more stable XPath or data-testid attribute.

this.compareButton = page.locator("button[data-action='compare']");

Example – after:

this.compareButton = page.locator("//button[@data-testid='btn-compare']");
// HEALED: 2026-06-28 – replaced stale CSS selector with data-testid XPath from live DOM

Healing a Timing Issue in Step Definition

1. Open the step definition file
2. Find the method where the timeout occurred
3. Add or increase page.waitForLoadState(LoadState.NETWORKIDLE) or locator.waitFor()
4. Save the file

Healing an Assertion Mismatch

1. Open the step definition file
2. Find the assertion that failed
3. If the actual value is the correct expected value, update the assertion
4. If the actual value signals a real bug, flag with // HEAL-CHECK: and do not auto-change
5. Ensure to use soft assertion or logging to capture the actual vs expected values for review where necessary.

Assertion healing decision:

• Whitespace / casing difference → fix automatically
• Different keyword (e.g. "Identical" vs "identical") → fix automatically
• Completely different semantic value → add // HEAL-CHECK: actual="..." expected="..." and skip

Step 6: Re-Run After Healing

After each healing change:

1. Re-execute only the failed step (not the full scenario) using Playwright MCP
2. If it passes: mark as HEALED, continue to next step
3. If it fails again: increment healing iteration counter
4. After 3 healing iterations with no success: mark as HEAL-FAILED, add comment, move on

Step 7: Final Report

After all scenarios complete, output a structured report:

==================================================
 PLAYWRIGHT TEST EXECUTION REPORT
 Date: <timestamp>
 Target: <feature file / tag>
 Base URL: <url>
==================================================

SUMMARY
  Total Scenarios : X
  Passed          : X
  Failed          : X
  Healed & Passed : X
  Heal-Failed     : X

--------------------------------------------------
SCENARIO RESULTS
--------------------------------------------------
[PASS]  Compare two identical text inputs
[HEALED] Compare two texts with minor differences
  → Healed: TextComparisonPage.java:compareButton locator (data-testid xpath)
  → Healed: TextComparisonToolSteps.java:toolIndicatesEquality() – added NETWORKIDLE wait
[FAIL]  <scenario name>
  → Step: "the tool highlights the exact words or characters that differ"
  → Error: ElementNotFound – .diff-highlight not in DOM after 3 healing attempts
  → Screenshot: failure_highlightsDifferences_step4.png
  → HEAL-FAILED comment added at TextComparisonToolSteps.java:122

--------------------------------------------------
FILES MODIFIED
--------------------------------------------------
  {Page objects}/TextComparisonPage.java
    - compareButton locator: CSS → XPath (data-testid)
    - resultText locator: added fallback selector

  {Step definitions}/TextComparisonToolSteps.java
    - toolIndicatesEquality(): added page.waitForLoadState(LoadState.NETWORKIDLE)

--------------------------------------------------
NEXT STEPS
--------------------------------------------------
  1. Review HEAL-CHECK comments – these may indicate real application bugs
  2. Update HEAL-FAILED steps with correct locators once UI is finalized
  3. Update Page Object locators with confirmed data-testid attributes from the dev team
  4. Run full regression suite after locator updates are confirmed
==================================================

Healing Rules & Constraints

Automatic Healing (Safe)

• Replace stale CSS/XPath locators with ones discovered from fresh DOM
• Add or adjust waitFor / waitForLoadState timeouts (max 10 000 ms)
• Fix whitespace/casing in string assertion values
• Add page.waitForTimeout(500) after click/fill when race conditions detected
• Narrow ambiguous selectors by adding a parent anchor or additional attribute

Requires Human Review (Flag Only)

• Assertion value change where actual vs expected are semantically different
• Navigation URL changes (may indicate environment config issues)
• Step logic that contradicts the feature file description
• Failures that occur on every healing iteration (structural/app bug)
• Any change that would modify a Cucumber annotation or method signature

Never Do Automatically

• Delete or rename step definition methods
• Remove Cucumber annotations
• Change expected test data that is explicitly specified in the feature file
• Modify scenario or step names in feature files

Implementation Guidelines

Locator Selection Priority

Follow the same XPath priority hierarchy defined in 3_pwlocator.prompt.md:

1. data-testid, data-*
2. Stable unique id
3. name, aria-label, role
4. placeholder, title, alt
5. Visible text (normalize-space())
6. Parent-anchored relative XPath

Page Object Healing Pattern

// Before
this.resultText = page.locator("#comparison-result, .result, [class*='result']");

// After (healed from live DOM)
this.resultText = page.locator("//div[@data-testid='comparison-result']");
// HEALED: 2026-06-28 – fresh DOM shows data-testid='comparison-result' on outer div

Step Definition Healing Pattern

// Before (timing issue)
public void toolIndicatesEquality() {
    String result = comparisonPage.getResultText();
    Assert.assertNotNull("Comparison result should be displayed", result);
}

// After (healed)
public void toolIndicatesEquality() {
    page.waitForLoadState(LoadState.NETWORKIDLE);
    String result = comparisonPage.getResultText();
    Assert.assertNotNull("Comparison result should be displayed", result);
    Assert.assertFalse("Result should contain comparison information", result.trim().isEmpty());
}
// HEALED: 2026-06-28 – added NETWORKIDLE wait; comparison API call was still in-flight

Example Workflow Execution

User Input:

• Target: {Feature files}/KAN-4.feature
• Base URL: http://localhost:4200
• Browser: chromium (headless)

Agent Processing:

1. ✓ Parses KAN-4.feature – found 2 scenarios, 10 steps
2. ✓ Maps steps to {Step definitions}/TextComparisonToolSteps.java methods
3. ✓ Launches chromium via Playwright MCP → navigates to http://localhost:4200
4. ✓ Scenario 1 "Compare two identical text inputs" – all 5 steps PASS
5. ✗ Scenario 2 "Compare two texts with minor differences" – step 4 FAILS
   • Error: ElementNotFound for .diff-highlight selector
   • Screenshot captured: failure_highlightsDifferences_step4.png
   • Diagnosis: stale CSS selector – live DOM uses data-testid='diff-highlight-container'
   • Healing iteration 1: updated {Page objects}/TextComparisonPage.java highlightedDifferences locator
   • Re-run step 4 → PASS
6. ✓ All 10 steps now PASS
7. ✓ Report generated – 1 file modified, 1 locator healed