feat(browser): declarative browser action connectors

[michaelmcnees]

Closes #33

Summary

• Adds seven declarative browser connectors backed by a shared Playwright JS script generator: browser/navigate, browser/click, browser/fill, browser/extract, browser/screenshot, browser/wait, browser/evaluate
• Session state (cookies, localStorage, current URL) is serialized to a session_state blob on output and restored on input, enabling stateful multi-step browser automation without persistent containers
• All connectors delegate to the existing DockerRunConnector pipeline — no new infrastructure
• buildDeclarativeScript generates complete, self-contained Playwright scripts with proper error propagation

Test plan

• go test ./internal/connector/ -short -run TestBrowser — all 30 unit tests pass
• go test ./internal/connector/ -run TestBrowserNavigateExtract_SessionChain -v -timeout 120s — session chain works end-to-end
• go test ./internal/connector/ -run TestBrowserWait_TimeoutError_Integration -v -timeout 30s — timeout surfaces as error

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added browser automation actions: navigate, click, fill, extract, screenshot, wait, and evaluate JavaScript on web pages.
  • Browser sessions maintain state (cookies and localStorage) across chained actions for complex workflows.

• Tests

  • Comprehensive unit and integration tests for all browser actions and session persistence.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Introduces a declarative browser automation layer with seven new connector actions (navigate, click, fill, extract, screenshot, wait, evaluate) that generate and execute Playwright scripts inside Docker containers while maintaining browser session state across multiple sequential actions.

Changes

Declarative Browser Automation Actions

Layer / File(s)	Summary
Session and Script Infrastructure packages/engine/internal/connector/browser_declarative.go (lines 1–180)	BrowserSession struct holds cookies, localStorage, and URL; extractSession parses optional session state from params; buildDeclarativeScript generates self-contained Playwright Node.js scripts that optionally restore cookies/localStorage, run an injected action snippet, and capture updated session state; executeBrowserScript runs scripts via DockerRunConnector and parses JSON output; extractTimeoutMs and mustJSONString provide helper utilities.
Browser Action Connectors packages/engine/internal/connector/browser_declarative.go (lines 182–455)	Seven action connector implementations: BrowserNavigateConnector navigates and captures page title, BrowserEvaluateConnector runs arbitrary JS expressions, BrowserWaitConnector waits for selectors/URL patterns/durations, BrowserScreenshotConnector captures base64 screenshots, BrowserExtractConnector retrieves text or attribute values from selectors, BrowserFillConnector fills form fields, BrowserClickConnector clicks elements with optional wait-for conditions. Each validates required parameters, generates a Playwright action snippet, executes via the infrastructure layer, and returns session state plus action-specific outputs.
Helper and Infrastructure Tests packages/engine/internal/connector/browser_declarative_test.go (lines 1–139)	Unit tests for extractSession covering absent, nil, valid, and invalid inputs; extractTimeoutMs covering defaults and provided values; buildDeclarativeScript verifying script generation for fresh and session-restored scenarios with optional URL restoration.
Connector Unit Tests packages/engine/internal/connector/browser_declarative_test.go (lines 141–480)	Parameter validation and script generation tests for all seven connectors, verifying required field enforcement, invalid session state rejection, and correct embedding of Playwright method calls (page.click, page.fill, page.textContent, page.getAttribute, page.waitForSelector, page.waitForURL, page.waitForTimeout, page.evaluate) in generated scripts.
Integration Tests and Registry Wiring packages/engine/internal/connector/browser_declarative_test.go (lines 481–634), packages/engine/internal/connector/connector.go (lines 43–49)	Docker-based integration tests exercising end-to-end navigation, session chaining through extract/screenshot/evaluate, base64 validation, and timeout error handling (skipped in short mode); registration of all seven browser action connectors in NewRegistry.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 A rabbit hops through scripts so neat,
Seven actions, a complete feat!
Navigate, fill, and extract with care,
Sessions preserved in the Playwright air! 🌐

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(browser): declarative browser action connectors' clearly and concisely describes the main change—adding declarative browser automation connectors.
Linked Issues check	✅ Passed	All code changes implement the seven proposed actions (navigate, fill, click, extract, screenshot, wait, evaluate) with session state support as specified in issue #33.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the declarative browser connectors required by issue #33; no unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/browser-automation-v060

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 832ce055c4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Restore localStorage before page loads

When a chained browser step restores session_state, this navigation runs before the saved localStorage entries are written back, so any app that reads localStorage during initial load (for example token-based auth or route guards) sees an empty store and may redirect or render as logged out before the connector restores it. This breaks the advertised session handoff for sites that keep session data outside cookies; inject the stored values before navigation (for example with an init script keyed by location.origin) so page startup observes them.

Useful? React with 👍 / 👎.