Skip to content

Commit 1c50236

Browse files
CopilotMossakaCopilot
authored
feat: add localhost keyword for playwright testing (#427)
* Initial plan * feat: add localhost keyword for playwright testing - Automatically maps 'localhost' to 'host.docker.internal' - Enables host access when localhost is specified - Configures common development ports (3000, 4200, 5173, 8080, etc.) - Supports protocol prefixes (http://localhost, https://localhost) - Preserves user-specified --allow-host-ports if provided - Add comprehensive integration tests for localhost functionality Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> * docs: add playwright localhost testing documentation - Add localhost keyword section to AGENTS.md - Add Playwright testing examples to README.md - Add comprehensive guide to docs/usage.md - Create dedicated Playwright testing guide in docs-site - Explain automatic configuration and security considerations Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> * docs: update CLI help text for localhost keyword Add localhost to --allow-domains help text explaining it auto-configures for local testing Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> * test: add unit tests for localhost keyword processing Extract localhost processing logic into testable function and add comprehensive unit tests covering: - Plain localhost, http://localhost, https://localhost variants - Protocol prefix preservation - Host access auto-enablement - Default port configuration - Edge cases and domain order preservation Coverage improvements: - Overall: 81.58% → 82.03% (+0.45%) - cli.ts lines: 37.82% → 41.47% (+3.65%) - cli.ts branches: 31.03% → 38.01% (+6.98%) Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> * fix: add security warning for localhost keyword host access Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> * test: verify security warning in localhost integration test Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> Co-authored-by: Copilot <copilot@github.com> Co-authored-by: Jiaxiao (mossaka) Zhou <duibao55328@gmail.com>
1 parent fd0078c commit 1c50236

10 files changed

Lines changed: 610 additions & 5 deletions

File tree

‎AGENTS.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,27 @@ Containers stopped, temporary files cleaned up
257257
- `.github.com` → matches all subdomains
258258
- Squid denies any domain not in the allowlist
259259
260+
### Localhost Keyword
261+
262+
The `localhost` keyword provides simplified access to host services for Playwright testing and local development:
263+
264+
**Usage:**
265+
```bash
266+
sudo awf --allow-domains localhost,playwright.dev -- npx playwright test
267+
```
268+
269+
**Automatic configuration when `localhost` is specified:**
270+
1. Maps `localhost` to `host.docker.internal` (Docker's host gateway)
271+
2. Enables `--enable-host-access` automatically
272+
3. Allows common development ports: 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 8888, 9000, 9090
273+
4. Preserves protocol prefixes (`http://localhost` → `http://host.docker.internal`)
274+
275+
**Customization:**
276+
- Use `--allow-host-ports` to override the default port list
277+
- Example: `--allow-domains localhost --allow-host-ports 3000,8080`
278+
279+
**Security note:** The localhost keyword enables access to host services. Only use for trusted workloads like local testing and development.
280+
260281
## Exit Code Handling
261282

262283
The wrapper propagates the exit code from the agent container:

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,15 @@ sudo -E awf \
3636
-- copilot --prompt "List my repositories"
3737
```
3838

39+
### Playwright Testing Localhost (out of the box)
40+
41+
```bash
42+
# Start your dev server, then test it:
43+
sudo awf --allow-domains localhost,playwright.dev -- npx playwright test
44+
```
45+
46+
The `localhost` keyword automatically configures everything for local testing.
47+
3948
For checksum verification, version pinning, and manual installation steps, see [Quick start](docs/quickstart.md).
4049

4150
#### GitHub Action (recommended for CI/CD)

‎containers/agent/setup-iptables.sh‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,8 @@ if [ -n "$AWF_ALLOW_HOST_PORTS" ]; then
174174
if [[ $port_spec == *"-"* ]]; then
175175
# Port range (e.g., "3000-3010")
176176
echo "[iptables] Redirect port range $port_spec to Squid..."
177-
iptables -t nat -A OUTPUT -p tcp -m multiport --dports "$port_spec" -j DNAT --to-destination "${SQUID_IP}:${SQUID_PORT}"
177+
# For port ranges, use --dport with range syntax (without multiport)
178+
iptables -t nat -A OUTPUT -p tcp --dport "$port_spec" -j DNAT --to-destination "${SQUID_IP}:${SQUID_PORT}"
178179
else
179180
# Single port (e.g., "3000")
180181
echo "[iptables] Redirect port $port_spec to Squid..."

‎docs-site/src/content/docs/guides/playwright-testing.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
title: Playwright Testing with Localhost
3+
description: Test local web applications with Playwright through the firewall
4+
---
5+
6+
The firewall makes it easy to test local web applications with Playwright using the `localhost` keyword.
7+
8+
## Quick Start
9+
10+
Test a local development server with Playwright:
11+
12+
```bash
13+
# Start your dev server (e.g., npm run dev on port 3000)
14+
15+
# Run Playwright tests through the firewall
16+
sudo awf --allow-domains localhost,playwright.dev -- npx playwright test
17+
```
18+
19+
The `localhost` keyword automatically configures everything needed for local testing - no manual setup required.
20+
21+
## What the localhost Keyword Does
22+
23+
When you include `localhost` in `--allow-domains`, awf automatically:
24+
25+
1. **Enables host access** - Activates `--enable-host-access` flag
26+
2. **Maps to host.docker.internal** - Replaces `localhost` with Docker's host gateway
27+
3. **Allows development ports** - Opens common dev ports: 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 8888, 9000, 9090
28+
29+
This means your Playwright tests inside the container can reach services running on your host machine's localhost.
30+
31+
## Protocol Prefixes
32+
33+
The `localhost` keyword preserves HTTP/HTTPS protocol prefixes:
34+
35+
```bash
36+
# HTTP only
37+
sudo awf --allow-domains http://localhost -- npx playwright test
38+
39+
# HTTPS only
40+
sudo awf --allow-domains https://localhost -- npx playwright test
41+
42+
# Both HTTP and HTTPS (default)
43+
sudo awf --allow-domains localhost -- npx playwright test
44+
```
45+
46+
## Custom Port Configuration
47+
48+
Override the default port list with `--allow-host-ports`:
49+
50+
```bash
51+
# Allow only specific ports
52+
sudo awf \
53+
--allow-domains localhost \
54+
--allow-host-ports 3000,8080 \
55+
-- npx playwright test
56+
57+
# Allow a port range
58+
sudo awf \
59+
--allow-domains localhost \
60+
--allow-host-ports 3000,8080-8090 \
61+
-- npx playwright test
62+
```
63+
64+
:::note
65+
Port ranges must avoid dangerous ports (SSH, databases, etc.). See the [security model](/gh-aw-firewall/concepts/security-model) for details.
66+
:::
67+
68+
## Example: Testing a Next.js App
69+
70+
```bash
71+
# Terminal 1: Start Next.js dev server
72+
npm run dev
73+
# Server runs on http://localhost:3000
74+
75+
# Terminal 2: Run Playwright tests through firewall
76+
sudo awf \
77+
--allow-domains localhost,vercel.app,next.js.org \
78+
-- npx playwright test
79+
```
80+
81+
Your Playwright tests can now access `http://localhost:3000` and also fetch from `vercel.app` and `next.js.org`.
82+
83+
## Example: Testing a React App with External APIs
84+
85+
```bash
86+
# Start React dev server on port 3000
87+
npm start
88+
89+
# Run tests with access to localhost and external APIs
90+
sudo awf \
91+
--allow-domains localhost,api.github.com,cdn.example.com \
92+
-- npx playwright test
93+
```
94+
95+
## Without the localhost Keyword
96+
97+
Before the `localhost` keyword, you had to manually configure host access:
98+
99+
```bash
100+
# Old way (still works)
101+
sudo awf \
102+
--enable-host-access \
103+
--allow-domains host.docker.internal \
104+
--allow-host-ports 3000,8080 \
105+
-- npx playwright test
106+
```
107+
108+
The `localhost` keyword eliminates this boilerplate.
109+
110+
## Security Considerations
111+
112+
:::caution
113+
The `localhost` keyword enables access to services running on your host machine. Only use it for trusted workloads like local testing and development.
114+
:::
115+
116+
When `localhost` is specified:
117+
- Containers can access ANY service on the specified ports on your host machine
118+
- This includes local databases, development servers, and other services
119+
- This is safe for local development but should not be used in production
120+
121+
## Troubleshooting
122+
123+
### "Connection refused" errors
124+
125+
If Playwright can't connect to your local server:
126+
127+
1. **Verify server is running:** Check that your dev server is actually running on the host
128+
2. **Check the port:** Ensure the port is in the allowed list (default: 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 8888, 9000, 9090)
129+
3. **Use custom ports:** If using a different port, specify it with `--allow-host-ports`
130+
131+
### "Host not found" errors
132+
133+
If you see DNS resolution errors:
134+
135+
- Use `localhost` (not `127.0.0.1` or your machine's hostname)
136+
- The `localhost` keyword maps to `host.docker.internal` which resolves to the host
137+
138+
### Server binds to 127.0.0.1 only
139+
140+
Some dev servers bind only to 127.0.0.1. To make them accessible from Docker containers:
141+
142+
```bash
143+
# Bind to 0.0.0.0 instead of 127.0.0.1
144+
npm run dev -- --host 0.0.0.0
145+
146+
# Or for Vite/Vue
147+
npm run dev -- --host
148+
149+
# Or for Next.js
150+
npm run dev -- -H 0.0.0.0
151+
```
152+
153+
## See Also
154+
155+
- [Server Connectivity](/gh-aw-firewall/guides/server-connectivity) - Connecting to HTTP, HTTPS, and gRPC servers
156+
- [Security Model](/gh-aw-firewall/concepts/security-model) - Understanding the firewall's security guarantees
157+
- [CLI Reference](/gh-aw-firewall/reference/cli-reference) - All command-line options

‎docs/usage.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,31 @@ sudo awf \
5454
'curl https://api.github.com'
5555
```
5656

57+
### Playwright Testing Localhost
58+
59+
Test local web applications with Playwright without complex configuration:
60+
61+
```bash
62+
# Start your dev server (e.g., npm run dev on port 3000)
63+
# Then run Playwright tests through the firewall:
64+
sudo awf \
65+
--allow-domains localhost,playwright.dev \
66+
'npx playwright test'
67+
```
68+
69+
The `localhost` keyword automatically:
70+
- Enables access to host services via `host.docker.internal`
71+
- Allows common development ports (3000, 4200, 5173, 8080, etc.)
72+
- Works with both HTTP and HTTPS protocols
73+
74+
You can customize the ports with `--allow-host-ports`:
75+
```bash
76+
sudo awf \
77+
--allow-domains localhost \
78+
--allow-host-ports 3000,8080 \
79+
'npx playwright test'
80+
```
81+
5782
### With GitHub Copilot CLI
5883

5984
```bash

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)