Skip to content

WORKSHOP-1.md

Latest commit

 

History

History
219 lines (152 loc) · 7.83 KB

WORKSHOP-1.md

File metadata and controls

219 lines (152 loc) · 7.83 KB

Workshop 1: Background Agent and Playwright Basics

← Back to Overview Next Workshop: Copilot CLI →

Goal

Set up Playwright (TypeScript), generate a first UI test with a background agent (Copilot Chat in VS Code), and run it locally.

Story

Tailspin Games asks you to prevent regressions in the new T‑Rex runner. You'll draft smoke tests and let an agent help with boilerplate.

As a developer on the Tailspin Games team, you've been tasked with ensuring the quality of the newly developed T‑Rex Runner game. The team wants to prevent any regressions as new features are added, so you'll set up automated testing using Playwright. Rather than writing all the boilerplate yourself, you'll leverage GitHub Copilot as a background agent to help generate the initial test structure.

Prerequisites

Before starting this workshop:

  • Node.js 20+ installed
  • VS Code installed
  • GitHub Copilot and GitHub Copilot Chat extensions enabled
  • T‑Rex Runner application downloaded and extracted

Steps

1. Initialize Playwright (TypeScript)

First, let's set up Playwright in the client application.

  1. Open a terminal and navigate to the client directory:

    cd trex-agents-workshop/apps/client

  2. Initialize Playwright with TypeScript support:

    npm create @playwright/test@latest -- --yes

    This command will:

    • Install Playwright and its dependencies
    • Set up configuration files
    • Choose TypeScript as the default language

  3. Install the required browsers:

    npx playwright install

📚 Reference: For more details on Playwright's TypeScript setup, see the official Playwright TS docs.

2. Start the Application Stack

The T‑Rex Runner consists of two parts: a backend API and a frontend UI. You'll need both running to test the application.

  1. Terminal A - Start the backend server:

    npm run dev -w apps/server

    You should see output indicating the server is running (typically on port 3000).

  2. Terminal B - Start the frontend client:

    npm run dev -w apps/client

    The frontend will typically run on http://localhost:5173

  3. Open your browser and navigate to http://localhost:5173 to verify the app is running. You should see the T‑Rex Runner game.

3. Use a Background Agent (Copilot Chat)

Now comes the exciting part - using GitHub Copilot as a background agent to help generate your first test!

  1. In VS Code, open the Copilot Chat panel (you can use the Copilot icon in the sidebar or press Ctrl+Shift+I / Cmd+Shift+I).

  2. In Copilot Chat, enter the following prompt:

    Create a Playwright test in TypeScript that opens http://localhost:5173, asserts the canvas is visible, performs one jump, waits until the score increases, and takes a trace.

  3. Review the generated code. Copilot should provide you with a test that:

    • Imports necessary Playwright modules
    • Sets up a test case
    • Navigates to the application
    • Locates the game canvas
    • Simulates a jump action (typically space bar or click)
    • Waits for the score to update
    • Includes tracing configuration

  4. Create a new file: apps/client/tests/trex-smoke.spec.ts

  5. Copy the generated code into this file.

  6. Add the following configuration at the top of your test file to enable tracing on the first retry:

    test.use({ trace: 'on-first-retry' });

💡 Tip: The trace: 'on-first-retry' configuration helps with debugging by recording a trace only when a test fails and is retried.

4. Run Your Tests

Now let's execute the test and view the results.

  1. In the terminal (from the apps/client directory), run:

    npx playwright test

  2. View the HTML report:

    npx playwright show-report

  3. Review the test results:

    • Check if the test passed
    • Look at the execution time
    • Examine any screenshots or traces if the test failed

5. (Optional) Stabilize Locators

For more resilient tests, it's best practice to use accessibility-based locators rather than CSS selectors.

  1. Open apps/client/index.html

  2. Find the canvas element and add an aria-label:

    <canvas id="game-canvas" aria-label="game-canvas"></canvas>

  3. Update your test to use the accessibility locator:

    // Instead of: await page.locator('#game-canvas')
await page.getByLabel('game-canvas')

  4. Re-run your tests to ensure they still pass:

    npx playwright test

📚 Why accessibility labels? Using aria-label and getByLabel() creates tests that are:

  • More resilient to UI changes
  • Better for accessibility
  • Easier to understand and maintain

What You Learned

In this workshop, you:

✅ Set up Playwright with TypeScript for modern browser testing
✅ Used a background agent (GitHub Copilot Chat) to generate test code
✅ Ran automated tests and viewed detailed reports
✅ Applied best practices for creating resilient, accessibility-friendly locators
✅ Understood the value of using AI to draft boilerplate test code while you validate and refine

Key Takeaways

  1. Background agents can accelerate test creation: Instead of writing boilerplate from scratch, use Copilot to generate the initial structure
  2. Always validate AI-generated code: Review and test the generated code to ensure it meets your requirements
  3. Accessibility-first locators are more resilient: Using ARIA labels makes tests more stable and improves your app's accessibility
  4. Tracing helps debugging: The trace: 'on-first-retry' option provides valuable debugging information when tests fail

Troubleshooting

Test fails to find elements:

  • Ensure both the server and client are running
  • Check that the URL in the test matches your local development server
  • Verify the canvas element exists by manually opening the browser

Playwright installation issues:

  • Try running npx playwright install --force
  • Check your Node.js version (should be 20+)

Browser doesn't open:

  • Run with headed mode to see what's happening: npx playwright test --headed
  • Check if ports 3000 and 5173 are available

Stretch Ideas

Want to go further? Try these challenges:

  1. Add more test scenarios:

    • Test the pause/resume functionality
    • Test the restart feature
    • Verify high score persistence

  2. Test different browsers:

    • Configure Playwright to run tests in Chrome, Firefox, and Safari
    • Compare execution times across browsers

  3. Add visual regression testing:

    • Use Playwright's screenshot comparison features
    • Set up baseline images for key game states

  4. Create a test helper:

    • Extract common game interactions into reusable functions
    • Build a Page Object Model for the T‑Rex Runner

Next Steps

Congratulations! You've set up your testing foundation and learned how to use a background agent to accelerate test creation.

In Workshop 2, you'll learn how to use the GitHub Copilot CLI to create reusable skills for test orchestration and iteratively improve your testing workflow.

Resources

← Back to Overview Next Workshop: Copilot CLI →