Camofox Browser
Camofox quickstart: create a test tab, read a snapshot and verify the result
Follow a minimal localhost REST workflow with explicit identity, authentication and snapshot checks before attempting actions or importing credentials.
What you will learn
- userId and sessionKey identify state, not authorization.
- Verify URL, snapshot and refs before acting.
- Paginate captured snapshots, and refresh after page changes.
Before you start
- Basic HTTP and JSON knowledge
- An isolated service and an owned or permitted test page
Explain the chapter’s actual service boundary and verify the proposed observation or lifecycle fixture.
Key takeaways
- userId and sessionKey identify state, not authorization.
- Verify URL, snapshot and refs before acting.
- Paginate captured snapshots, and refresh after page changes.
Start with a protected local service
Use a reviewed installation bound to loopback, with a global access key supplied through your secret-handling mechanism. The deployment chapter explains the package and browser requirements. This exercise does not need imported cookies, a proxy, tracing or a public listener. Begin with example.com or a page you operate, without submitting forms or authenticating to third-party accounts.
POST /tabs requires userId and sessionKey in the inspected handler. sessionKey is the preferred name for a tab group; listItemId remains a legacy alternative. Give the experiment a distinct user and group label, save the returned tab ID, and do not confuse these routing identifiers with bearer-token authentication. A label identifies state; it does not prove who may control it.
Read what the browser actually observed
Request GET /tabs/:tabId/snapshot with the same userId. Check the returned URL, snapshot text and reference count before planning any interaction. For a known fixture, verify its heading and field labels. If references are absent, distinguish a page with no relevant controls from a snapshot-generation failure instead of inventing a selector or clicking a remembered coordinate.
For large observations, inspect truncated, hasMore and nextOffset. Continue using the returned offset rather than assuming the first response contains every control. The inspected positive-offset path can reuse lastSnapshot, so it is pagination through a captured observation, not a promise of a freshly read page. After changing the page, request a fresh initial snapshot before interpreting later chunks.
Finish the experiment without broad cleanup
Only attempt an action after identifying its target in current state and confirming that the action is within the test’s authorization. If a navigation or dynamic update makes a reference stale, observe again and reassess the intended operation. Do not blindly replay a form submission because an HTTP response was delayed; check whether the visible result already changed.
Close the specific test tab when finished and verify it is absent from the test user’s tab list. Deleting a whole user session or persisted storage has a wider effect and is unnecessary for this first observation exercise. The request example below is a proposed REST body, not evidence that this review launched the browser or performed a live-site action.
Implementation steps
- 1
Start the isolated service with loopback binding and an access key.
- 2
POST the sample body to /tabs and retain its returned tab ID.
- 3
GET /tabs/:tabId/snapshot?userId=fixture-reader with the same bearer token.
- 4
Check the expected heading, then close only the created test tab.
Copy-ready example
{"userId":"fixture-reader","sessionKey":"read-only-20260908","url":"https://example.com","trace":false}Frequently asked questions
Is sessionKey another API key?
No. It names a tab group in the session. Authentication is separately carried in the Authorization header.
Does requesting a later offset refresh the page?
Not necessarily. The inspected handler serves positive offsets from lastSnapshot when it exists.
Sources
- README.mdSource checked 2026-09-08
- package.jsonSource checked 2026-09-08
- DockerfileSource checked 2026-09-08
- lib/auth.jsSource checked 2026-09-08
- lib/snapshot.jsSource checked 2026-09-08
- lib/extract.jsSource checked 2026-09-08
- lib/config.jsSource checked 2026-09-08
- lib/reporter.jsSource checked 2026-09-08
- lib/page-lease.jsSource checked 2026-09-08
- server.jsSource checked 2026-09-08
- tests/unit/snapshot.test.jsSource checked 2026-09-08
- tests/unit/auth.test.jsSource checked 2026-09-08