docs/dev_b_prd.md

PRD – Dev B: Browser Layer (Playwright Interaction)

This document defines the requirements and approach for the Browser Layer, whose sole purpose is to automate and interact with Codenames.game using Playwright. The goal is to provide a clean, reliable API for the Server Layer, focusing on robust automation and maintainability. Simplicity is paramount: the implementation should avoid unnecessary complexity, use clear abstractions, and prioritize ease of understanding and modification.

---

1 • Goal

To implement the Browser Layer module responsible for interacting with the Codenames.game website using Playwright. This layer will encapsulate all browser automation logic, exposing a clean API for the Server Layer to consume.

---

2 • Key Technologies

• Playwright: For browser automation and interaction.
• Chromium: The target browser controlled by Playwright.
• Node.js & TypeScript: For the implementation environment.
• ICodenamesBrowser Interface: The contract defining the API exposed to the Server Layer.

---

2.1 • API Abstraction & Testing Philosophy

The Browser Layer must expose a technology-agnostic API (see ICodenamesGameAPI in shared/types.ts). This API should only describe game concepts and actions, not how they are implemented.

Why?

• This abstraction allows the underlying implementation to change (e.g., switching from Playwright to a Bridge) without breaking the contract with the Server Layer.
• It enables robust, maintainable tests:
  • Public API tests (in handler.test.ts) validate only observable game behavior, not implementation details.

Benefits:

• Implementation-agnostic, future-proof API
• Robust, maintainable test suite
• Clear separation of concerns

---

3 • Responsibilities & Deliverables

• Implement Playwright Logic:
  • Launch and manage a Chromium browser instance.
  • Navigate to the Codenames.game website and handle room joining/setup if necessary.
  • Reliably scrape the DOM to extract current game state (board words, team turn, etc.).
  • Execute game actions based on API calls (e.g., clicking clue input, typing clue, clicking words, clicking end turn button).
• Expose API:
  • Implement the ICodenamesBrowser interface (defined in shared/types.ts or agreed upon with Dev A). This interface will serve as the contract between the Browser and Server layers.
• Testing:
  • Develop unit and integration tests within the browser/tests/ directory to verify Playwright interactions, selectors, and state extraction logic independently.
• Deliverables:
  • browser/handler.ts: Core implementation of the browser interaction logic and API.
  • browser/selectors.ts: (Optional but recommended) Centralized repository for CSS/XPath selectors to mitigate UI change risks.
  • browser/tests/: Unit and integration tests for the Browser Layer.

---

4 • ICodenamesBrowser Interface (Contract)

(To be finalized and agreed upon with Dev A)

This interface defines the methods the Server Layer will call. Example methods might include:

interface ICodenamesBrowser {
  launchBrowser(options?: any): Promise<void>;
  closeBrowser(): Promise<void>;
  navigateToGame(url: string): Promise<void>;
  getBoardState(): Promise<BoardState>; // Define BoardState structure
  getTeamTurn(): Promise<'red' | 'blue'>;
  submitClue(clue: string, count: number): Promise<void>;
  makeGuess(word: string): Promise<void>;
  endTurn(): Promise<void>;
  // ... other necessary methods
}

---

5 • Suggested Folder Structure (Focus Area)

spymaster/                 # cwd
├── browser/               # <-- Your primary focus
│   ├── handler.ts         # Core implementation
│   ├── selectors.ts       # (Optional) Selector definitions
│   └── tests/             # Unit/integration tests
├── shared/                # For shared types like ICodenamesBrowser
│   └── types.ts
├── ... (other project files)

---

6 • Development Steps

1. Setup & Interface Agreement:
   • Set up the browser/ directory structure.
   • Critically: Collaborate with Dev A to finalize and agree on the ICodenamesBrowser interface definition. This is your contract.
2. Independent Implementation:
   • Implement the browser/handler.ts class/functions to fulfill the ICodenamesBrowser interface.
   • Focus on robust Playwright scripting:
     • Use reliable selectors (consider browser/selectors.ts).
     • Handle potential timing issues (waits, retries).
     • Implement state scraping logic.
     • Implement action execution logic.
3. Local Testing:
   • Write and run unit/integration tests in browser/tests/ to verify your Playwright code directly against a live or mock Codenames game instance. Ensure state is scraped correctly and actions execute as expected.
4. Integration & Debugging:
   • Once Dev A has a functional Server Layer and the project is built/linked (npm run build, npm link), participate in E2E testing initiated via npx your-package-name.
   • Debug any Playwright-related issues (selector changes, timing problems, incorrect state) identified during E2E testing.

---

7 • Testing Approach

• Primary: Unit and integration tests (browser/tests/) are crucial for verifying the core Playwright logic without relying on the full MCP stack. Use these to test:
  • Browser launching and navigation.
  • Accuracy of DOM scraping and state extraction.
  • Correct execution of clicks, typing, etc.
• Secondary: Participate in E2E testing led by Dev A using MCP Inspector against the npx-launched application to catch integration issues.

7.1 • Testing Environment: Explicit Requirements

• Single, Always-Live Test Room:

  • All Playwright tests in browser/tests/ must use the same, pre-designated Codenames.game room for all test runs.
  • The test room must be referred to by its room code only (e.g., web-bean-lip), not the full URL.
  • The base URL must be set in the environment variable CODENAMES_BASE_URL (e.g., https://codenames.game/room/).
  • The room code must be set in the environment variable CODENAMES_TEST_ROOM_CODE (e.g., web-bean-lip).
  • Tests must construct the full room URL by concatenating CODENAMES_BASE_URL and CODENAMES_TEST_ROOM_CODE.
  • The test room is always live and shared.
  • Each test suite must use a beforeAll hook to:
    • Set up the Playwright browser and page.
    • Navigate to the constructed room URL.
    • Join the room as needed.
  • Each test suite must use an afterAll hook to:
    • Leave the room if possible.
    • Close the page and the Playwright browser.
  • The setup and teardown logic used in beforeAll and afterAll must be extracted into reusable functions (e.g., setupBrowserAndJoinRoom, leaveRoomAndTeardownBrowser). These functions must be tested independently in dedicated test files to ensure reliability and debuggability.
  • Note: The file test-assets/playwright/join_room.test.ts exists and performs room join and clue actions. This test must not be run during the Dev B process, as it may interfere with the shared test room and ongoing development or testing activities. However, it can serve as a valuable reference for implementing Playwright-based room interaction and automation logic.

• Robustness to Unknown State:

  • Tests must be written to handle any possible state the room may be in at the start of the test (e.g., in-progress game, finished game, unexpected board/clue log).
  • Where possible, tests should attempt to bring the room to a desired state by interacting with the UI (e.g., clicking "New Game"), but must not assume this always succeeds or is possible.
  • Tests must be resilient to failures due to unexpected room state and should log the current state at the start of each test for debugging.

• Documentation:

  • Add a browser/tests/README.md that:
    • Specifies that the test room code is configured via the CODENAMES_TEST_ROOM_CODE environment variable.
    • Specifies that the base URL is configured via the CODENAMES_BASE_URL environment variable.
    • Describes any manual steps required to prepare the room for testing.
    • Provides a step-by-step guide for running tests locally.

---

8 • Key Risks & Mitigations

• Codenames.game UI Changes: Selectors breaking is the highest risk.
  • Mitigation:
    • Use stable selector strategies (IDs where possible, robust CSS/XPath).
    • Centralize selectors in browser/selectors.ts for easier updates.
    • Rely on comprehensive tests (browser/tests/) to catch breakages quickly.
• Race Conditions/Timing Issues: Playwright actions failing due to the web page not being ready.
  • Mitigation: Use Playwright's built-in auto-waits, explicit waits (waitForSelector, waitForFunction), and potentially retry logic where appropriate.
• Interface Mismatch: Browser Layer implementation deviating from the agreed ICodenamesBrowser interface.
  • Mitigation: Strict adherence to the TypeScript interface definition. Early and frequent communication with Dev A if changes seem necessary.

---

9 • Acceptance Criteria

• The browser/handler.ts module successfully implements all methods defined in the agreed-upon ICodenamesBrowser interface.
• Unit/integration tests in browser/tests/ pass, demonstrating:
  • Successful browser launch and navigation to Codenames.game.
  • Accurate retrieval of game state (board, turn, clues) via API methods.
  • Successful execution of game actions (giving clue, making guess, ending turn) via API methods.
• During E2E testing (run via npx your-package-name), the Browser Layer correctly responds to Server Layer requests initiated via MCP Inspector, reflecting accurate game state and performing actions in the Chromium window.
• Code is well-structured, potentially using browser/selectors.ts for maintainability.