core/go-webview
8
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions
go-webview/CLAUDE.md
Snider 900cb750cf
All checks were successful
Security Scan / security (pull_request) Successful in 10s
Details
Test / test (pull_request) Successful in 30s
Details
fix(console): buffer trim panic when limit < 100, add unit tests 
CLAUDE.md: update error wrapping guidance to reflect coreerr.E() convention.

Console buffer trimming in both Webview.addConsoleMessage and
ConsoleWatcher.addMessage panicked with slice bounds out of range
when consoleLimit was smaller than 100. Use min(100, len) for safe
batch trimming.

Added 22 unit tests covering pure functions (FormatConsoleOutput,
containsString, findString, formatJSValue, getString), ConsoleWatcher
filter/count/handler logic, ExceptionWatcher operations, WaitAction
context handling, and buffer limit enforcement. Coverage: 3.2% → 16.1%.

DX audit findings:
- Error handling: clean (all coreerr.E(), no fmt.Errorf)
- File I/O: clean (no os.ReadFile/os.WriteFile — package uses HTTP/WS only)

Co-Authored-By: Virgil <virgil@lethean.io>
2026-03-17 08:54:22 +00:00

3.3 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Module: forge.lthn.ai/core/go-webview — Chrome DevTools Protocol client for browser automation.

Commands

go test ./...                          # Run all tests (must pass before commit)
go test -v -run TestActionSequence_Good ./...  # Run a single test
gofmt -w .                             # Format code
go vet ./...                           # Static analysis

Prerequisites

Tests and usage require a running Chrome/Chromium with --remote-debugging-port=9222. The package does not launch Chrome itself. Verify with curl http://localhost:9222/json.

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Headless (CI)
google-chrome --headless=new --remote-debugging-port=9222 --no-sandbox --disable-gpu

Architecture

Application Code → Webview (high-level API) → CDPClient (WebSocket transport) → Chrome

Single flat package (package webview). No sub-packages.

File Layer Purpose
cdp.go Transport WebSocket connection, CDP message framing, event dispatch. No browser-level logic.
webview.go High-level API Navigate, Click, Type, Screenshot, DOM queries, console capture. Application-facing.
actions.go Action system Action interface + concrete types (ClickAction, TypeAction, etc.) + fluent ActionSequence builder.
console.go Diagnostics ConsoleWatcher (filtered console capture) and ExceptionWatcher (JS exception tracking).
angular.go SPA helpers Angular-specific: Zone.js stability, router navigation, component introspection, ngModel access.

Key patterns:

  • CDPClient.Call(ctx, method, params) sends a CDP command and blocks for the response via a pending-channel map.
  • Events flow from Chrome → readLoop goroutine → registered handlers (each dispatched in its own goroutine).
  • Webview enables Runtime, Page, and DOM CDP domains on construction; console capture starts immediately.
  • New action types: add struct + Execute method in actions.go, builder method on ActionSequence, _Good test.
  • New SPA framework helpers: create <framework>.go following the angular.go pattern.

Coding Standards

  • UK English in all comments, docs, and commit messages (behaviour, colour, initialise)
  • EUPL-1.2 licence header (// SPDX-License-Identifier: EUPL-1.2) in every Go file
  • Conventional commits: type(scope): description (scopes: cdp, angular, console, actions)
  • Co-author trailer on every commit: Co-Authored-By: Virgil <virgil@lethean.io>
  • Test naming: _Good (happy path), _Bad (expected errors), _Ugly (panics/edge cases)
  • Standard testing.T only — no test frameworks
  • Wrap errors with coreerr.E("Scope.Method", "description", err) from go-log, never fmt.Errorf
  • Protect shared state with sync.RWMutex; copy handler slices before calling outside lock

Docs

  • docs/architecture.md — CDP connection, DOM queries, console capture, Angular helpers
  • docs/development.md — prerequisites, build/test, coding standards, adding actions
  • docs/history.md — completed phases, known limitations, future considerations

Forge Push

git push ssh://git@forge.lthn.ai:2223/core/go-webview.git HEAD:main