feat: add local-test skill and Dockerfile.test for web gateway testing (#524)

Add Dockerfile.test as reusable infrastructure for spinning up local test instances with libsql (no PostgreSQL dependency). Defaults to port 3003 to avoid conflict with dev server. Add local-test workspace skill that teaches the agent how to build, run, and test against local Docker containers using Chrome MCP browser automation tools. Covers LLM backend configuration, multi-instance testing, cleanup, and troubleshooting.
2026-08-25 14:53:34 +00:00 · 2026-03-04 05:53:35 +00:00
parent 308758c27c
commit bf2a08be94
2 changed files with 282 additions and 0 deletions
@@ -0,0 +1,225 @@
+---
+name: local-test
+version: 0.1.0
+description: Build, run, and test IronClaw locally using Docker containers and Chrome MCP browser automation.
+activation:
+  keywords:
+    - test locally
+    - local test
+    - docker test
+    - test my changes
+    - test in docker
+    - test web gateway
+    - spin up test
+    - test container
+  patterns:
+    - "test.*local"
+    - "docker.*test"
+    - "spin.*up.*test"
+    - "test.*changes.*docker"
+  max_context_tokens: 3000
+---
+
+# Local Testing with Docker + Chrome MCP
+
+Use this skill to build, run, and test IronClaw web gateway changes locally using `Dockerfile.test` and Chrome MCP browser automation tools.
+
+## Quick Start
+
+```bash
+# Build the test image (libsql-only, no PostgreSQL needed)
+docker build --platform linux/amd64 -f Dockerfile.test -t ironclaw-test .
+
+# Run on port 3003 (default)
+docker run --rm -p 3003:3003 \
+  -e ONBOARD_COMPLETED=true \
+  -e CLI_ENABLED=false \
+  -e NEARAI_API_KEY=<key> \
+  ironclaw-test
+
+# Open in browser
+# http://localhost:3003/?token=test
+```
+
+## Building the Image
+
+The test Dockerfile uses a two-stage build: Rust compilation with `--features libsql` (no PostgreSQL dependency), then a minimal Debian runtime image.
+
+```bash
+docker build --platform linux/amd64 -f Dockerfile.test -t ironclaw-test .
+```
+
+Build takes ~5-10 minutes on first run (cached subsequent builds are faster). The `--platform linux/amd64` flag avoids QEMU warnings on Apple Silicon but can be omitted if targeting native architecture.
+
+## Running Containers
+
+### Required Environment Variables
+
+| Variable | Purpose | Default in Dockerfile |
+|----------|---------|----------------------|
+| `ONBOARD_COMPLETED=true` | Skip onboarding wizard (exits immediately otherwise) | not set |
+| `CLI_ENABLED=false` | Disable TUI/REPL (causes EOF shutdown otherwise) | not set |
+
+### LLM Backend Configuration
+
+Pick ONE of these configurations:
+
+**NEAR AI (API key mode):**
+```bash
+docker run --rm -p 3003:3003 \
+  -e ONBOARD_COMPLETED=true \
+  -e CLI_ENABLED=false \
+  -e NEARAI_API_KEY=<your-key> \
+  ironclaw-test
+```
+
+**NEAR AI (session token mode):**
+```bash
+docker run --rm -p 3003:3003 \
+  -e ONBOARD_COMPLETED=true \
+  -e CLI_ENABLED=false \
+  -e NEARAI_SESSION_TOKEN=<sess_xxx> \
+  -e NEARAI_BASE_URL=https://private.near.ai \
+  ironclaw-test
+```
+
+**OpenAI:**
+```bash
+docker run --rm -p 3003:3003 \
+  -e ONBOARD_COMPLETED=true \
+  -e CLI_ENABLED=false \
+  -e LLM_BACKEND=openai \
+  -e OPENAI_API_KEY=<your-key> \
+  ironclaw-test
+```
+
+**Anthropic:**
+```bash
+docker run --rm -p 3003:3003 \
+  -e ONBOARD_COMPLETED=true \
+  -e CLI_ENABLED=false \
+  -e LLM_BACKEND=anthropic \
+  -e ANTHROPIC_API_KEY=<your-key> \
+  ironclaw-test
+```
+
+**Dummy run (no LLM, just test the UI loads):**
+```bash
+docker run --rm -p 3003:3003 \
+  -e ONBOARD_COMPLETED=true \
+  -e CLI_ENABLED=false \
+  -e NEARAI_API_KEY=dummy \
+  ironclaw-test
+```
+
+### Common Overrides
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `GATEWAY_PORT` | Change the listen port | `3003` (default) |
+| `GATEWAY_AUTH_TOKEN` | Auth token for API | `test` (default) |
+| `NEARAI_MODEL` | Override LLM model | `claude-3-5-sonnet-20241022` |
+| `RUST_LOG` | Logging verbosity | `ironclaw=debug` |
+| `ROUTINES_ENABLED` | Enable routines | `true`/`false` |
+| `SKILLS_ENABLED` | Enable skills system | `true` (default) |
+
+### Multi-Instance Testing
+
+Run multiple containers on different host ports:
+
+```bash
+docker run --rm -d --name ic-test-a -p 3003:3003 -e ONBOARD_COMPLETED=true -e CLI_ENABLED=false -e NEARAI_API_KEY=dummy ironclaw-test
+docker run --rm -d --name ic-test-b -p 3004:3003 -e ONBOARD_COMPLETED=true -e CLI_ENABLED=false -e NEARAI_API_KEY=dummy ironclaw-test
+```
+
+## Chrome MCP Testing Workflow
+
+Use the Claude for Chrome browser automation tools to test the web UI.
+
+### Step 1: Get Browser Context
+
+```
+mcp__claude-in-chrome__tabs_context_mcp
+```
+
+Always start here to see current tabs and get fresh tab IDs.
+
+### Step 2: Open the Gateway
+
+```
+mcp__claude-in-chrome__tabs_create_mcp  url=http://localhost:3003/?token=test
+```
+
+### Step 3: Verify the Page
+
+```
+mcp__claude-in-chrome__read_page
+```
+
+Check for:
+- "Connected" indicator in top-right
+- All tabs visible: Chat, Memory, Jobs, Routines, Extensions, Skills
+
+### Step 4: Take Screenshots
+
+```
+mcp__claude-in-chrome__computer  action=screenshot
+```
+
+### Step 5: Test Mobile Viewport
+
+```
+mcp__claude-in-chrome__resize_window  width=375  height=812
+mcp__claude-in-chrome__computer  action=screenshot
+```
+
+Reset to desktop:
+```
+mcp__claude-in-chrome__resize_window  width=1280  height=800
+```
+
+### Step 6: Run JavaScript Checks
+
+```
+mcp__claude-in-chrome__javascript_tool  script="document.querySelector('.connection-status')?.textContent"
+```
+
+### Step 7: Test Interactions
+
+Click tabs, send messages, search skills — use `computer` tool with `action=click` and coordinate-based clicks, or use `find` + `form_input` for text entry.
+
+## Cleanup
+
+```bash
+# Stop a specific container
+docker stop ic-test-a
+
+# Stop all test containers
+docker ps --filter ancestor=ironclaw-test -q | xargs -r docker stop
+
+# Remove the test image
+docker rmi ironclaw-test
+```
+
+## Troubleshooting
+
+### Container exits immediately
+- **Missing `ONBOARD_COMPLETED=true`**: The onboarding wizard tries to read stdin, gets EOF, and exits.
+- **Missing `CLI_ENABLED=false`**: The REPL channel reads stdin, gets EOF, and shuts down the agent.
+
+### "Model not found" or LLM errors
+- Check that your API key/token is valid and the model name is correct.
+- For NEAR AI session token mode, you also need `NEARAI_BASE_URL=https://private.near.ai`.
+
+### Platform mismatch warnings on Apple Silicon
+- The `--platform linux/amd64` flag causes QEMU emulation warnings — these are harmless.
+- Alternatively, omit the flag and build natively if your dependencies support ARM64.
+
+### Port already in use
+- The dev server defaults to port 3001; the test Dockerfile defaults to 3003 to avoid conflicts.
+- Use a different host port: `-p 3005:3003`.
+
+### Cannot connect from browser
+- Verify `GATEWAY_HOST=0.0.0.0` (set by default in Dockerfile).
+- Check the container logs: `docker logs <container-id>`.
+- Make sure you include the token query param: `?token=test`.