Skip to content

feat: add localhost keyword for playwright testing #427

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mossaka merged 10 commits into from
Feb 4, 2026
Merged

feat: add localhost keyword for playwright testing #427

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f3403bf
Initial plan
Copilot Jan 26, 2026
dc449d3
feat: add localhost keyword for playwright testing
Copilot Jan 26, 2026
fb598ac
docs: add playwright localhost testing documentation
Copilot Jan 26, 2026
f0db83f
docs: update CLI help text for localhost keyword
Copilot Jan 26, 2026
6b2e53e
merge: resolve conflicts from origin/main
Feb 3, 2026
6ba8651
test: add unit tests for localhost keyword processing
Copilot Feb 3, 2026
92cf5bc
merge: sync with origin/main
Copilot Feb 4, 2026
079ab78
fix: add security warning for localhost keyword host access
Copilot Feb 4, 2026
e7abfc2
test: verify security warning in localhost integration test
Copilot Feb 4, 2026
be36b68
Merge remote-tracking branch 'origin/main' into copilot/setup-playwri…
Mossaka Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -257,6 +257,27 @@ Containers stopped, temporary files cleaned up
- `.github.com` → matches all subdomains
- Squid denies any domain not in the allowlist

### Localhost Keyword

The `localhost` keyword provides simplified access to host services for Playwright testing and local development:

**Usage:**
```bash
sudo awf --allow-domains localhost,playwright.dev -- npx playwright test
```

**Automatic configuration when `localhost` is specified:**
1. Maps `localhost` to `host.docker.internal` (Docker's host gateway)
2. Enables `--enable-host-access` automatically
3. Allows common development ports: 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 8888, 9000, 9090
4. Preserves protocol prefixes (`http://localhost` → `http://host.docker.internal`)

**Customization:**
- Use `--allow-host-ports` to override the default port list
- Example: `--allow-domains localhost --allow-host-ports 3000,8080`

**Security note:** The localhost keyword enables access to host services. Only use for trusted workloads like local testing and development.

## Exit Code Handling

The wrapper propagates the exit code from the agent container:
Expand Down
9 changes: 9 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,15 @@ sudo -E awf \
-- copilot --prompt "List my repositories"
```

### Playwright Testing Localhost (out of the box)

```bash
# Start your dev server, then test it:
sudo awf --allow-domains localhost,playwright.dev -- npx playwright test
```

The `localhost` keyword automatically configures everything for local testing.

For checksum verification, version pinning, and manual installation steps, see [Quick start](docs/quickstart.md).

#### GitHub Action (recommended for CI/CD)
Expand Down
3 changes: 2 additions & 1 deletion containers/agent/setup-iptables.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,8 @@ if [ -n "$AWF_ALLOW_HOST_PORTS" ]; then
if [[ $port_spec == *"-"* ]]; then
# Port range (e.g., "3000-3010")
echo "[iptables] Redirect port range $port_spec to Squid..."
iptables -t nat -A OUTPUT -p tcp -m multiport --dports "$port_spec" -j DNAT --to-destination "${SQUID_IP}:${SQUID_PORT}"
# For port ranges, use --dport with range syntax (without multiport)
iptables -t nat -A OUTPUT -p tcp --dport "$port_spec" -j DNAT --to-destination "${SQUID_IP}:${SQUID_PORT}"
else
# Single port (e.g., "3000")
echo "[iptables] Redirect port $port_spec to Squid..."
Expand Down
157 changes: 157 additions & 0 deletions docs-site/src/content/docs/guides/playwright-testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
---
title: Playwright Testing with Localhost
description: Test local web applications with Playwright through the firewall
---

The firewall makes it easy to test local web applications with Playwright using the `localhost` keyword.

## Quick Start

Test a local development server with Playwright:

```bash
# Start your dev server (e.g., npm run dev on port 3000)

# Run Playwright tests through the firewall
sudo awf --allow-domains localhost,playwright.dev -- npx playwright test
```

The `localhost` keyword automatically configures everything needed for local testing - no manual setup required.

## What the localhost Keyword Does

When you include `localhost` in `--allow-domains`, awf automatically:

1. **Enables host access** - Activates `--enable-host-access` flag
2. **Maps to host.docker.internal** - Replaces `localhost` with Docker's host gateway
3. **Allows development ports** - Opens common dev ports: 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 8888, 9000, 9090

This means your Playwright tests inside the container can reach services running on your host machine's localhost.

## Protocol Prefixes

The `localhost` keyword preserves HTTP/HTTPS protocol prefixes:

```bash
# HTTP only
sudo awf --allow-domains http://localhost -- npx playwright test

# HTTPS only
sudo awf --allow-domains https://localhost -- npx playwright test

# Both HTTP and HTTPS (default)
sudo awf --allow-domains localhost -- npx playwright test
```

## Custom Port Configuration

Override the default port list with `--allow-host-ports`:

```bash
# Allow only specific ports
sudo awf \
--allow-domains localhost \
--allow-host-ports 3000,8080 \
-- npx playwright test

# Allow a port range
sudo awf \
--allow-domains localhost \
--allow-host-ports 3000,8080-8090 \
-- npx playwright test
```

:::note
Port ranges must avoid dangerous ports (SSH, databases, etc.). See the [security model](/gh-aw-firewall/concepts/security-model) for details.
:::

## Example: Testing a Next.js App

```bash
# Terminal 1: Start Next.js dev server
npm run dev
# Server runs on http://localhost:3000

# Terminal 2: Run Playwright tests through firewall
sudo awf \
--allow-domains localhost,vercel.app,next.js.org \
-- npx playwright test
```

Your Playwright tests can now access `http://localhost:3000` and also fetch from `vercel.app` and `next.js.org`.

## Example: Testing a React App with External APIs

```bash
# Start React dev server on port 3000
npm start

# Run tests with access to localhost and external APIs
sudo awf \
--allow-domains localhost,api.github.com,cdn.example.com \
-- npx playwright test
```

## Without the localhost Keyword

Before the `localhost` keyword, you had to manually configure host access:

```bash
# Old way (still works)
sudo awf \
--enable-host-access \
--allow-domains host.docker.internal \
--allow-host-ports 3000,8080 \
-- npx playwright test
```

The `localhost` keyword eliminates this boilerplate.

## Security Considerations

:::caution
The `localhost` keyword enables access to services running on your host machine. Only use it for trusted workloads like local testing and development.
:::

When `localhost` is specified:
- Containers can access ANY service on the specified ports on your host machine
- This includes local databases, development servers, and other services
- This is safe for local development but should not be used in production

## Troubleshooting

### "Connection refused" errors

If Playwright can't connect to your local server:

1. **Verify server is running:** Check that your dev server is actually running on the host
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)
3. **Use custom ports:** If using a different port, specify it with `--allow-host-ports`

### "Host not found" errors

If you see DNS resolution errors:

- Use `localhost` (not `127.0.0.1` or your machine's hostname)
- The `localhost` keyword maps to `host.docker.internal` which resolves to the host

### Server binds to 127.0.0.1 only

Some dev servers bind only to 127.0.0.1. To make them accessible from Docker containers:

```bash
# Bind to 0.0.0.0 instead of 127.0.0.1
npm run dev -- --host 0.0.0.0

# Or for Vite/Vue
npm run dev -- --host

# Or for Next.js
npm run dev -- -H 0.0.0.0
```

## See Also

- [Server Connectivity](/gh-aw-firewall/guides/server-connectivity) - Connecting to HTTP, HTTPS, and gRPC servers
- [Security Model](/gh-aw-firewall/concepts/security-model) - Understanding the firewall's security guarantees
- [CLI Reference](/gh-aw-firewall/reference/cli-reference) - All command-line options
25 changes: 25 additions & 0 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,31 @@ sudo awf \
'curl https://api.github.com'
```

### Playwright Testing Localhost

Test local web applications with Playwright without complex configuration:

```bash
# Start your dev server (e.g., npm run dev on port 3000)
# Then run Playwright tests through the firewall:
sudo awf \
--allow-domains localhost,playwright.dev \
'npx playwright test'
```

The `localhost` keyword automatically:
- Enables access to host services via `host.docker.internal`
- Allows common development ports (3000, 4200, 5173, 8080, etc.)
- Works with both HTTP and HTTPS protocols

You can customize the ports with `--allow-host-ports`:
```bash
sudo awf \
--allow-domains localhost \
--allow-host-ports 3000,8080 \
'npx playwright test'
```

### With GitHub Copilot CLI

```bash
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading