Add Playwright automation for AI agent game testing

[Copilot]

Enables programmatic control of the web game via Playwright for automated testing and AI agent interaction. Agents can now play complete games, control all 4 players, and detect bugs automatically.

Architecture

Three-layer bridge between Playwright and Pygbag/WebAssembly:

# Python automation layer
automation = AggravationAutomation(page)
state = page.evaluate("window.gameState.getFullState()")

# JavaScript API polls localStorage every 100ms
# Python exports state via state_exporter.py to localStorage
# Pygbag game runs normally with minimal integration hooks

Core Components

JavaScript API (web/index.html)

• window.gameState with 9 methods: getCurrentPlayer(), getMarblePositions(), getDiceRoll(), getValidMoves(), isGameOver(), getWinner(), getFullState(), getMoveLog(), isReady()
• Polls browser localStorage for real-time state updates

State Exporter (web/state_exporter.py)

• Exports Python game state to localStorage as JSON
• Logs dice rolls, moves, and valid move sets
• Integrated into aggravation_web.py with 4 minimal additions

Playwright Harness (tests/test_web_automation.py)

• AggravationAutomation class with game control methods
• 5 pytest tests covering initialization, state access, and full game simulation
• Anomaly detection with screenshot capture
• Configurable headless mode via HEADLESS env var

Example Usage

from playwright.sync_api import sync_playwright
from tests.test_web_automation import AggravationAutomation

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    
    automation = AggravationAutomation(page)
    results = automation.play_full_game(max_moves=100)
    # Returns: move_count, winner, final_state, anomalies

Files Changed

New:

• tests/test_web_automation.py - Automation harness (340 lines)
• web/state_exporter.py - State export module (85 lines)
• web/index.html - JavaScript API (200 lines)
• examples/simple_automation.py - Demo script (140 lines)
• Documentation: AUTOMATION.md, TESTING_AUTOMATION.md, tests/README.md, examples/README.md
• validate_automation_setup.py - Setup validator

Modified:

• web/aggravation_web.py - Added state export calls (+4 lines)
• .gitignore - Excluded automation artifacts

Setup & Usage

pip install -r requirements-automation.txt
playwright install chromium
cd web && ./build.sh --serve  # separate terminal
pytest tests/test_web_automation.py -v

Original prompt

---

This section details on the original issue you should resolve

<issue_title>feat: Add Playwright (Puppeteer or Selenium) automation for AI agent game testing</issue_title>
<issue_description>
Labels: testing, automation, enhancement

Description:

Problem

We want to enable a coding agent (like GitHub Copilot) to play the web version of Aggravation, controlling all
4 players and detecting bugs automatically.

Proposed Solution

Implement Playwright-based automation that enables programmatic game interaction.

Implementation Plan

1. Expose Game State to Browser Automation

   // Add to web version - expose state globally for Playwright
   window.gameState = {
     getCurrentPlayer: () => { ... },
     getMarblePositions: () => { ... },
     getDiceRoll: () => { ... },
     getValidMoves: () => { ... }
   };

2. Create Playwright Test Harness

   # tests/test_web_automation.py
   def test_full_game_simulation():
       with sync_playwright() as p:
           browser = p.chromium.launch()
           page = browser.new_page()
           page.goto("http://localhost:8000")

           # Play game for all 4 players
           while not page.evaluate("window.gameState.isGameOver()"):
               player = page.evaluate("window.gameState.getCurrentPlayer()")
               valid_moves = page.evaluate("window.gameState.getValidMoves()")

               if valid_moves:
                   # Click on a valid move
                   page.click(f"[data-position='{valid_moves[0]}']")
               else:
                   page.click("#roll-dice")

           # Log final state for bug analysis
           final_state = page.evaluate("window.gameState.getFullState()")
           print(json.dumps(final_state, indent=2))

3. Add MCP Tool for Agent Integration Consider adding a custom MCP server that wraps Playwright:

• aggravation_play_turn - Execute one turn for current player
• aggravation_get_state - Return full game state as JSON
• aggravation_click_position - Click on a board position
• aggravation_detect_bugs - Run validation checks on current state

Key Features for Agent Testing

• Expose game state via JavaScript API (window.gameState)
• Add data attributes to clickable elements for reliable selectors
• Create Playwright test suite for automated gameplay
• Log all moves and state transitions for bug detection
• Implement validation checks (e.g., invalid moves, stuck states)
• Screenshot capture on anomalies

Alternative: Puppeteer or Selenium

If Playwright isn't available, similar automation is possible with:

• Puppeteer (Node.js) - Same approach, different API
• Selenium (Python) - More setup, but widely supported

Acceptance Criteria

• Game state accessible via window.gameState API
• Playwright can programmatically play a complete game
• Agent can control all 4 players in sequence
• Bug detection logs created during automated play
• Documentation for agent integration</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes feat: Add Playwright (Puppeteer or Selenium) automation for AI agent game testing #51

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.