nexu-e2e-test: Скилл для сквозного тестирования

--- name: nexu-e2e-test description: Use when verifying OpenClaw gateway fixes end-to-end, testing skill loading after restart, or running integration tests against the local Nexu+OpenClaw stack. Triggers on "e2e test", "verify fix", "test gateway", "test skills loading". --- # Nexu E2E Testing — OpenClaw Gateway Run end-to-end verification of the Nexu → OpenClaw gateway stack locally. ## Known Constraints The OpenClaw gateway has architectural constraints that block naive E2E approaches. **Read this before attempting any gateway testing.** | Approach | Blocker | Status | |----------|---------|--------| | HTTP `POST /v1/chat/completions` | Endpoint exists (`openai-http.ts`) but uses `agentCommand()` — same embedded agent path as CLI, bypasses session store | Works for smoke tests (same as CLI) | | HTTP `POST /v1/responses` | Endpoint exists (`openresponses-http.ts`) but also uses `agentCommand()` | Works for smoke tests (same as CLI) | | WebSocket `chat.send` | Requires device pairing for `operator.write` scope — `clearUnboundScopes()` in `message-handler.ts:483-488` clears all self-declared scopes without device identity | Dead end without device keys | | `openclaw agent --session-id` | Uses embedded agent path (`sessionKey=unknown`), bypasses session store cache | Works for smoke tests, NOT for session-store bugs | | Direct module import from dist | Rollup bundles with hashed filenames, can't import individual modules | Dead end | | `tsx` from `/tmp` | Module resolution fails for imports outside project root | Dead end | | Vitest in-project `.test.ts` | Full module resolution, mocking, TypeScript support | **Primary method** | **Key insight:** All HTTP and CLI approaches use the embedded agent path via `agentCommand()` (imported from `commands/agent.js`). Only messages arriving through connected channels (Slack/Discord) go through `dispatchInboundMessage()` → auto-reply pipeline → `ensureSkillSnapshot()`, which is the code path that uses the session store. ## Viable Test Methods ### 1. Vitest Unit/Integration Tests (Primary) Write `.test.ts` files **inside the OpenClaw worktree** and run with vitest. This is the only reliable way to test internal functions like `ensureSkillsWatcher`, `getSkillsSnapshotVersion`, `ensureSkillSnapshot`. ```bash cd <OPENCLAW_WORKTREE> OPENCLAW_TEST_FAST=1 npx vitest run src/agents/skills/refresh.test.ts ``` Key patterns: - Mock `chokidar` with `vi.mock("chokidar", ...)` - Use `await import("./refresh.js")` for dynamic imports after mocking - Use unique workspace paths per test (`/tmp/test-<name>-${Date.now()}`) - `OPENCLAW_TEST_FAST=1` skips filesystem scanning in session-updates ### 2. `openclaw agent` CLI or HTTP Smoke Tests For "do skills load after restart" verification. Does NOT test session-store caching logic (all use embedded agent path). **CLI approach:** ```bash # Prerequisites: gateway must be running with a valid workspace OPENCLAW_STATE_DIR=~/.openclaw OPENCLAW_CONFIG_PATH=<config-with-local-workspace> openclaw agent --session-id "<session>" --message "<msg>" --json --timeout 60 ``` **HTTP approach (OpenAI-compatible):** ```bash curl -s http://localhost:18789/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer <gw-token>" -d '{"model":"default","messages":[{"role":"user","content":"list your skills"}]}' ``` Parse results (CLI JSON output): ```bash | python3 -c " import json,sys d=json.load(sys.stdin) entries=d.get('result',{}).get('meta',{}).get('systemPromptReport',{}).get('skills',{}).get('entries',[]) managed=[e['name'] for e in entries if e['name'] in ('static-deploy','test-greeting')] print(f'Skills: {len(entries)}, Managed: {managed}') " ``` ### 3. Connected Channel (Slack/Discord) The only way to test the full auto-reply pipeline with session-store caching. Requires a running channel with active bot. ## Gateway Setup for Testing ### Config Pitfall: `/data/` workspace path Production configs have `"workspace": "/data/openclaw/workspaces/..."` which doesn't exist locally. Create a test config: ```bash cat ~/.openclaw/openclaw.json | python3 -c " import json, sys cfg = json.load(sys.stdin) cfg['agents']['list'][0]['workspace'] = '/tmp/openclaw-test-workspace' json.dump(cfg, sys.stdout, indent=2) " > /tmp/openclaw-test-config.json ``` ### Start gateway with test config ```bash OPENCLAW_STATE_DIR=~/.openclaw OPENCLAW_CONFIG_PATH=/tmp/openclaw-test-config.json openclaw gateway run --allow-unconfigured --bind loopback --port 18789 --force --verbose ``` ### Wait for port readiness (not just process start) ```bash for i in $(seq 1 15); do lsof -i :18789 -P 2>/dev/null | grep -q LISTEN && break sleep 1 done ``` ## WebSocket Protocol Reference If you ever need to attempt WS testing (e.g., after implementing device pairing): | Detail | Value | |--------|-------| | Frame format | `{"type": "req", "id": "<uuid>", "method": "...", "params": {...}}` (NOT JSON-RPC) | | Protocol version | `3` (as of 2026.2.25) | | Valid client IDs | `gateway-client`, `cli`, `webchat-ui`, `openclaw-control-ui`, `node-host`, `test`, `webchat`, `fingerprint`, `openclaw-probe`, `openclaw-macos`, `openclaw-ios`, `openclaw-android` (defined in `protocol/client-info.ts`) | | Valid client modes | `webchat`, `cli`, `ui`, `backend`, `node`, `probe`, `test` | | Auth flow | Challenge → `connect` RPC with nonce → needs device identity for write scopes | | Scope for `chat.send` | `operator.write` — requires device pairing, token-only auth gets zero scopes | | Scope exception | `controlUiAuthPolicy.allowBypass: true` preserves scopes without device identity (dev/control-UI only, see `message-handler.ts:489-542`) | ## Restart Verification Checklist When verifying a fix that involves skills/sessions after gateway restart: 1. **Build the fix:** `cd <worktree> && pnpm build` 2. **Link globally:** `cd <worktree> && pnpm link --global` 3. **Verify version:** `openclaw --version` 4. **Write unit tests** in the worktree for core logic (vitest) 5. **Run smoke test:** gateway restart → `openclaw agent` → check skill count 6. **Check sessions.json** at `~/.openclaw/agents/<agent>/sessions/sessions.json` for snapshot versions 7. **Check logs** at gateway stdout for skill watcher events ## Session Store Locations ``` ~/.openclaw/agents/<agent-id>/sessions/sessions.json # Session entries with skillsSnapshot ~/.openclaw/agents/<agent-id>/sessions/<session-id>.jsonl # Session transcript ``` Key fields in session entry: - `skillsSnapshot.version` — timestamp, should be non-zero after fix - `skillsSnapshot.skills[]` — array of loaded skill names and locations - `skillsSnapshot.prompt` — the `<available_skills>` XML injected into system prompt