|
| 1 | +# Generating Accessibility Reports |
| 2 | + |
| 3 | +Build a CLI tool that analyzes web page accessibility using the Playwright MCP server and generates detailed WCAG-compliant reports with optional test generation. |
| 4 | + |
| 5 | +> **Runnable example:** [recipe/AccessibilityReport.java](recipe/AccessibilityReport.java) |
| 6 | +> |
| 7 | +> ```bash |
| 8 | +> jbang recipe/AccessibilityReport.java |
| 9 | +> ``` |
| 10 | +
|
| 11 | +## Example scenario |
| 12 | +
|
| 13 | +You want to audit a website's accessibility compliance. This tool navigates to a URL using Playwright, captures an accessibility snapshot, and produces a structured report covering WCAG criteria like landmarks, heading hierarchy, focus management, and touch targets. It can also generate Playwright test files to automate future accessibility checks. |
| 14 | +
|
| 15 | +## Prerequisites |
| 16 | +
|
| 17 | +Install [JBang](https://www.jbang.dev/) and ensure `npx` is available (Node.js installed) for the Playwright MCP server: |
| 18 | +
|
| 19 | +```bash |
| 20 | +# macOS (using Homebrew) |
| 21 | +brew install jbangdev/tap/jbang |
| 22 | +
|
| 23 | +# Verify npx is available (needed for Playwright MCP) |
| 24 | +npx --version |
| 25 | +``` |
| 26 | +
|
| 27 | +## Usage |
| 28 | +
|
| 29 | +```bash |
| 30 | +jbang recipe/AccessibilityReport.java |
| 31 | +# Enter a URL when prompted |
| 32 | +``` |
| 33 | +
|
| 34 | +## Full example: AccessibilityReport.java |
| 35 | +
|
| 36 | +```java |
| 37 | +///usr/bin/env jbang "$0" "$@" ; exit $? |
| 38 | +//DEPS com.github:copilot-sdk-java:0.2.1-java.1 |
| 39 | +
|
| 40 | +import com.github.copilot.sdk.*; |
| 41 | +import com.github.copilot.sdk.events.*; |
| 42 | +import com.github.copilot.sdk.json.*; |
| 43 | +import java.io.*; |
| 44 | +import java.util.*; |
| 45 | +import java.util.concurrent.*; |
| 46 | +
|
| 47 | +public class AccessibilityReport { |
| 48 | + public static void main(String[] args) throws Exception { |
| 49 | + System.out.println("=== Accessibility Report Generator ===\n"); |
| 50 | +
|
| 51 | + var reader = new BufferedReader(new InputStreamReader(System.in)); |
| 52 | +
|
| 53 | + System.out.print("Enter URL to analyze: "); |
| 54 | + String url = reader.readLine().trim(); |
| 55 | + if (url.isEmpty()) { |
| 56 | + System.out.println("No URL provided. Exiting."); |
| 57 | + return; |
| 58 | + } |
| 59 | + if (!url.startsWith("http://") && !url.startsWith("https://")) { |
| 60 | + url = "https://" + url; |
| 61 | + } |
| 62 | +
|
| 63 | + System.out.printf("%nAnalyzing: %s%n", url); |
| 64 | + System.out.println("Please wait...\n"); |
| 65 | +
|
| 66 | + try (var client = new CopilotClient()) { |
| 67 | + client.start().get(); |
| 68 | +
|
| 69 | + // Configure Playwright MCP server for browser automation |
| 70 | + Map<String, Object> mcpConfig = Map.of( |
| 71 | + "type", "local", |
| 72 | + "command", "npx", |
| 73 | + "args", List.of("@playwright/mcp@latest"), |
| 74 | + "tools", List.of("*") |
| 75 | + ); |
| 76 | +
|
| 77 | + var session = client.createSession( |
| 78 | + new SessionConfig() |
| 79 | + .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) |
| 80 | + .setModel("claude-opus-4.6") |
| 81 | + .setStreaming(true) |
| 82 | + .setMcpServers(Map.of("playwright", mcpConfig)) |
| 83 | + ).get(); |
| 84 | +
|
| 85 | + // Stream output token-by-token |
| 86 | + var idleLatch = new CountDownLatch(1); |
| 87 | +
|
| 88 | + session.on(AssistantMessageDeltaEvent.class, |
| 89 | + ev -> System.out.print(ev.getData().deltaContent())); |
| 90 | +
|
| 91 | + session.on(SessionIdleEvent.class, |
| 92 | + ev -> idleLatch.countDown()); |
| 93 | +
|
| 94 | + session.on(SessionErrorEvent.class, ev -> { |
| 95 | + System.err.printf("%nError: %s%n", ev.getData().message()); |
| 96 | + idleLatch.countDown(); |
| 97 | + }); |
| 98 | +
|
| 99 | + String prompt = """ |
| 100 | + Use the Playwright MCP server to analyze the accessibility of this webpage: %s |
| 101 | +
|
| 102 | + Please: |
| 103 | + 1. Navigate to the URL using playwright-browser_navigate |
| 104 | + 2. Take an accessibility snapshot using playwright-browser_snapshot |
| 105 | + 3. Analyze the snapshot and provide a detailed accessibility report |
| 106 | +
|
| 107 | + Format the report with emoji indicators: |
| 108 | + - 📊 Accessibility Report header |
| 109 | + - ✅ What's Working Well (table with Category, Status, Details) |
| 110 | + - ⚠️ Issues Found (table with Severity, Issue, WCAG Criterion, Recommendation) |
| 111 | + - 📋 Stats Summary (links, headings, focusable elements, landmarks) |
| 112 | + - ⚙️ Priority Recommendations |
| 113 | +
|
| 114 | + Use ✅ for pass, 🔴 for high severity issues, 🟡 for medium severity, ❌ for missing items. |
| 115 | + Include actual findings from the page analysis. |
| 116 | + """.formatted(url); |
| 117 | +
|
| 118 | + session.send(new MessageOptions().setPrompt(prompt)); |
| 119 | + idleLatch.await(); |
| 120 | +
|
| 121 | + System.out.println("\n\n=== Report Complete ===\n"); |
| 122 | +
|
| 123 | + // Prompt user for test generation |
| 124 | + System.out.print("Would you like to generate Playwright accessibility tests? (y/n): "); |
| 125 | + String generateTests = reader.readLine().trim(); |
| 126 | +
|
| 127 | + if (generateTests.equalsIgnoreCase("y") || generateTests.equalsIgnoreCase("yes")) { |
| 128 | + var testLatch = new CountDownLatch(1); |
| 129 | +
|
| 130 | + session.on(SessionIdleEvent.class, |
| 131 | + ev -> testLatch.countDown()); |
| 132 | +
|
| 133 | + String testPrompt = """ |
| 134 | + Based on the accessibility report you just generated for %s, |
| 135 | + create Playwright accessibility tests in Java. |
| 136 | +
|
| 137 | + Include tests for: lang attribute, title, heading hierarchy, alt text, |
| 138 | + landmarks, skip navigation, focus indicators, and touch targets. |
| 139 | + Use Playwright's accessibility testing features with helpful comments. |
| 140 | + Output the complete test file. |
| 141 | + """.formatted(url); |
| 142 | +
|
| 143 | + System.out.println("\nGenerating accessibility tests...\n"); |
| 144 | + session.send(new MessageOptions().setPrompt(testPrompt)); |
| 145 | + testLatch.await(); |
| 146 | +
|
| 147 | + System.out.println("\n\n=== Tests Generated ==="); |
| 148 | + } |
| 149 | +
|
| 150 | + session.close(); |
| 151 | + } |
| 152 | + } |
| 153 | +} |
| 154 | +``` |
| 155 | +
|
| 156 | +## How it works |
| 157 | +
|
| 158 | +1. **Playwright MCP server**: Configures a local MCP server running `@playwright/mcp` to provide browser automation tools |
| 159 | +2. **Streaming output**: Uses `streaming: true` and `AssistantMessageDeltaEvent` for real-time token-by-token output |
| 160 | +3. **Accessibility snapshot**: Playwright's `browser_snapshot` tool captures the full accessibility tree of the page |
| 161 | +4. **Structured report**: The prompt engineers a consistent WCAG-aligned report format with emoji severity indicators |
| 162 | +5. **Test generation**: Optionally generates Playwright accessibility tests based on the analysis |
| 163 | +
|
| 164 | +## Key concepts |
| 165 | +
|
| 166 | +### MCP server configuration |
| 167 | +
|
| 168 | +The recipe configures a local MCP server that runs alongside the session: |
| 169 | +
|
| 170 | +```java |
| 171 | +Map<String, Object> mcpConfig = Map.of( |
| 172 | + "type", "local", |
| 173 | + "command", "npx", |
| 174 | + "args", List.of("@playwright/mcp@latest"), |
| 175 | + "tools", List.of("*") |
| 176 | +); |
| 177 | +
|
| 178 | +var session = client.createSession( |
| 179 | + new SessionConfig() |
| 180 | + .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) |
| 181 | + .setMcpServers(Map.of("playwright", mcpConfig)) |
| 182 | +).get(); |
| 183 | +``` |
| 184 | +
|
| 185 | +This gives the model access to Playwright browser tools like `browser_navigate`, `browser_snapshot`, and `browser_click`. |
| 186 | + |
| 187 | +### Streaming with events |
| 188 | + |
| 189 | +Unlike `sendAndWait`, this recipe uses streaming for real-time output: |
| 190 | + |
| 191 | +```java |
| 192 | +session.on(AssistantMessageDeltaEvent.class, |
| 193 | + ev -> System.out.print(ev.getData().deltaContent())); |
| 194 | + |
| 195 | +session.on(SessionIdleEvent.class, |
| 196 | + ev -> idleLatch.countDown()); |
| 197 | +``` |
| 198 | + |
| 199 | +A `CountDownLatch` synchronizes the main thread with the async event stream — when the session becomes idle, the latch releases and the program continues. |
| 200 | + |
| 201 | +## Sample interaction |
| 202 | + |
| 203 | +``` |
| 204 | +=== Accessibility Report Generator === |
| 205 | +
|
| 206 | +Enter URL to analyze: github.com |
| 207 | +
|
| 208 | +Analyzing: https://github.com |
| 209 | +Please wait... |
| 210 | +
|
| 211 | +📊 Accessibility Report: GitHub (github.com) |
| 212 | +
|
| 213 | +✅ What's Working Well |
| 214 | +| Category | Status | Details | |
| 215 | +|----------|--------|---------| |
| 216 | +| Language | ✅ Pass | lang="en" properly set | |
| 217 | +| Page Title | ✅ Pass | "GitHub" is recognizable | |
| 218 | +| Heading Hierarchy | ✅ Pass | Proper H1/H2 structure | |
| 219 | +| Images | ✅ Pass | All images have alt text | |
| 220 | +
|
| 221 | +⚠️ Issues Found |
| 222 | +| Severity | Issue | WCAG Criterion | Recommendation | |
| 223 | +|----------|-------|----------------|----------------| |
| 224 | +| 🟡 Medium | Some links lack descriptive text | 2.4.4 | Add aria-label to icon-only links | |
| 225 | +
|
| 226 | +📋 Stats Summary |
| 227 | +- Total Links: 47 |
| 228 | +- Total Headings: 8 (1× H1, proper hierarchy) |
| 229 | +- Focusable Elements: 52 |
| 230 | +- Landmarks Found: banner ✅, navigation ✅, main ✅, footer ✅ |
| 231 | +
|
| 232 | +=== Report Complete === |
| 233 | +
|
| 234 | +Would you like to generate Playwright accessibility tests? (y/n): y |
| 235 | +
|
| 236 | +Generating accessibility tests... |
| 237 | +[Generated test file output...] |
| 238 | +
|
| 239 | +=== Tests Generated === |
| 240 | +``` |
0 commit comments