Real Browser Qa Ceki Main

real-browser-qa-ceki — real Chrome for QA & security testing

Use responsibly. This skill drives someone's real browser for testing. Only test sites you own or have explicit authorization to test.

⚠️ THIS IS A LIVE BROWSER OF A REAL PERSON — NOT HEADLESS, NOT A SANDBOX

• Real person, real Chrome. Their screen, mouse, IP, fingerprint, cookies, open tabs. Not headless. Not CI. Not a test sandbox.
• Behave like a real user. Realistic pacing, no burst-clicks, tight loops, or parallel operations.
• No synthetic smokes. example.com, httpbin — FORBIDDEN. Only the real target.
• One active tab per session. New tab → switch_tab closes the previous one.
• Reuse ONE session. Each new session(mode=incognito) opens a new incognito window on the person's screen.
• Clean up after yourself. Don't leave junk tabs/forms/logins behind.

🚫 NO DIRECT API CALLS — UI ONLY

Critical rule: interact with sites through the browser UI, NOT through their APIs.

Why: API calls bypass the real browser's IP, cookies, and fingerprint. The site's backend sees a server-side request from your machine, NOT from the rented browser. This:

• Instantly flags the session as automation
• Wastes the rental — you paid for a real browser fingerprint but aren't using it
• Gets the provider's IP banned, not yours

Exception: Only the site's own frontend JS making XHR/fetch (which the page initiates naturally when you click buttons). YOU don't call APIs directly.

Interaction priority pyramid

🥇  ceki CLI commands          — navigate, click, type --natural, scroll
    ↓                          (what the CLI/sdk provides — real events, realistic interaction)
🥈  ceki cdp Input.*           — click at coords, key events, scroll
    ↓                          (CDP methods that produce real input events — for text-fallback clicks)
🥉  ceki cdp Runtime.evaluate  — read DOM, get element coords, blur field
    ↓                          (read-only or coordinate-fetching — never for writing data)
🚫  Direct HTTP API            — curl, fetch, GraphQL — FORBIDDEN

Golden rule: If you can do it with ceki navigate/click/type/scroll — do it. If not, use CDP to READ the DOM and extract coordinates, then click with ceki click or ceki cdp Input.dispatchMouseEvent. Direct value-setting via CDP Runtime.evaluate is LAST RESORT for rich editors only.

---

🧠 Realistic User Simulation for QA Testing

Headless browsers miss real-world issues. A headless Chrome doesn't render the same, doesn't carry the same fingerprint, doesn't trigger the same code paths. Realistic user simulation — with natural pacing, mouse trajectories, scroll patterns — reveals bugs that headless mode hides: layout shifts, conditional loading, JS-dependent validation, timing races, and anti-fingerprinting checks.

Below is a QA-oriented guide to realistic browser interaction. Follow this on every test session.

Core principle

Automated (naive):   type-type-click-scroll-click — all in 0.5s → ❌ unrealistic, masks bugs
Realistic QA:        open → pause 1-3s → scroll → pause → type... → pause → click → ✅ tests real UX

Every interaction should have:

1. A realistic pause before it (user looks at the screen, moves the mouse, thinks)
2. Natural trajectory (mouse doesn't teleport; cursor moves along a path)
3. Logical sequence (user fills top-to-bottom, not random order)

Realistic vs unrealistic interaction table

What this enables for QA

Behavioural profiles

Ready-made profiles in profiles/*.json. Each profile is a preset of interaction parameters for a specific user type. The CLI auto-selects via CEKI_HUMAN_PROFILE.

Session flow for QA testing

1. PAGE LOAD
   → Wait 1-3 seconds. Let lazy content load. Snapshot to compare render.

2. FIRST SCROLL
   → Scroll 20-40% of viewport. Pause 500-1500ms. Check for layout shift.
   → Scroll further if content is long. Check infinite scroll, lazy images.

3. FIRST INTERACTION
   → Hover (~300ms curve). Click. Wait 500-1000ms for response.

4. FORM FILL (if testing a form)
   → Field by field. Between fields, pause 300-900ms.
   → After 3-4 fields, scroll to review. Pause to "check".

5. SUBMIT
   → Before submit, pause 500-1500ms ("reviewing the form").
   → Click submit. Wait 2-5 seconds for response.

⚠️ Common testing gotchas

Summary

+ Realistic user simulation reveals bugs that headless/naive automation misses.
+ See a CAPTCHA? That's your testing environment behaving as expected — delegate solve to a human test engineer.
+ Profile mismatch (wrong geo, wrong language, wrong behaviour)? Switch profile and re-run the test.

---

📋 TASK TRACKING — create a server-side task before every job

Every browser rental session must be tracked as a task on the server. Don't just do work in files/chat.

Before starting any browser work, create a task:

# Step 0: Create a task on the server
ceki contract create --label "Real-browser: " \
  --status 100 --type 2 \
  --benefitable agent:N --desc "Task: 

Plan:
1. Rent browser
2. Navigate to target
3. ..."

# Note the returned event_id (eid), then:
ceki timelog start 

When the session completes:

ceki contract progress  --status 222 --desc "Done: "
ceki timelog stop  --label "Completed browser session"

Why: Without a server-side task, there's no tracking, no audit, no handoff. The issues-ceki system exists for this — use it.

---

When to use this — and when NOT to

✅ Appropriate use cases

• QA / E2E of your own web apps — drive a real browser through user flows on a site you own, catching layout shifts, timing bugs, and conditional rendering that headless tests miss
• Security testing & vulnerability discovery — test your own sites against real browser fingerprints, WAF rules, CSRF/CORS behaviour in authentic browser conditions
• Accessibility audits of sites you are responsible for — test with real rendering, screen reader compatibility, keyboard navigation
• Cross-browser inconsistency detection — run the same test through different geo/IP/behavioural profiles to surface geo-blocks, A/B test splits, and locale-specific bugs
• Synthetic monitoring — heartbeat your own services through real browser sessions
• Customer support automation — actions in your own dashboards, on behalf of your own users with their consent
• Data collection from public-record sites, open APIs presented as HTML, news — respecting robots.txt and ToS
• Auth-required flows on accounts you own (2FA, OTP, password manager fills, session cookies)

❌ NOT appropriate — ever

• Sites you don't own and whose ToS don't permit automated access
• Account creation on services other than your own

❌ NOT appropriate — ever

• Sites you don't own and whose ToS don't permit automated access
• Account creation on services other than your own
• Filling forms with data that isn't yours or isn't accurate
• Bypassing access controls, login walls, age gates, or paywalls
• Banking / KYC / payments under another identity
• Anything that violates local law where you, the host, or the target operates

If unsure: don't use it, ask first.

Privacy and visibility

Screenshots and chat messages are visible to the host (marketplace) and to the renter (earn). The server does not retain cookies or storage between rentals. If you need persistence, use ceki profile export/import locally.

---

Pre-flight — run before EVERY rent

Do NOT jump straight to ceki rent. Walk through these steps in order.

0. Create a server-side task (first!)

Before any browser work — create a task on the server and start the timer:

ceki contract create --label "Real-browser:  " --status 100 --type 2 \
  --benefitable agent:N --desc "Plan: 1) Rent 2) Navigate 3) ..."
ceki timelog start 

1. Check active sessions — resume, don't re-rent

If you already have an active session — resume it, don't start a new one.

ceki sessions
# If you see an active entry → ceki rent --resume 
# If none → proceed to step 2

A relay session lives forever (RELAY_RESUME_GRACE_MS=-1) until you call ceki stop. Returning after a pause? Your session is still there — ceki sessions finds it, ceki rent --resume reconnects. No need to re-rent from scratch.

2. Check your own browsers

ceki my-browsers
# → list of your browser_id with online/offline status
# If at least one is online → proceed to rent
# If all are busy (in use) → do NOT jump to public search

3. Public search — only if explicitly authorized

If my-browsers is empty or all busy, do not run ceki search without explicit permission — this is a public marketplace that rents other people's browsers for money.

When authorized:

ceki search
# → list of available browsers with geo, price, rating
# Pick one, then rent by its schedule_id

4. Install CLI (one-time)

pip install --upgrade ceki-sdk --break-system-packages   # >=2.18.0
ceki --help

5. Verify auth

curl -s -H "Authorization: Bearer $CEKI_API_KEY" \
  https://api.ceki.me/api/auth/introspect | jq '.tokenable_id, .name'

---

Modes

This skill works in two modes, controlled by how you configure it:

---

SDK installation

Via clawhub (Claude Code / Cline / Cursor)

clawhub skill install realbrowser

This copies the skill to your agent workspace and sets up the recommended permissions.

Via pip / npm

pip install --upgrade ceki-sdk --break-system-packages   # >=2.18.0
ceki --help

TypeScript: npm install @ceki/sdk (or npm install -g @ceki/sdk).

Authentication

Self mode (env-driven)

Set these env vars (e.g. in .claude/settings.json):

{
  "env": {
    "CEKI_TOKEN": "ag_xxxxxxxxxxxx",
    "CEKI_API_KEY": "ag_xxxxxxxxxxxx",
    "CEKI_RENT_SCHEDULES": "12345,67890"
  }
}

Marketplace (generic)

1. Register at ceki.me
2. Create a Sanctum token: dashboard → Profile → API Keys
3. Pass as token= to the SDK

---

Quickstarts

Python

import asyncio
from ceki_sdk import Browser

async def main():
    async with Browser(token="YOUR_TOKEN") as br:
        async with await br.session(mode="incognito", domain_hints=["example.com"]) as s:
            await s.navigate("https://example.com")
            title = await s.query("h1")
            print(title.text)

asyncio.run(main())

TypeScript

import { Browser } from '@ceki/sdk';

const br = new Browser({ token: 'YOUR_TOKEN' });
await br.connect();
const s = await br.openSession({ mode: 'incognito', domainHints: ['example.com'] });
await s.navigate('https://example.com');
const title = await s.query('h1');
console.log(title.elements[0]?.textContent);
await s.close();
await br.close();

CLI — rental loop (env-driven)

MODE="${CEKI_RENT_MODE:-main}"

# Determine browsers: from env or public search
if [ -z "${CEKI_RENT_SCHEDULES// /}" ]; then
  mapfile -t SCHEDS < <(ceki search --limit 20 | jq -r '.[].schedule_id // empty')
else
  IFS=',' read -ra SCHEDS <<< "$CEKI_RENT_SCHEDULES"
fi

[ ${#SCHEDS[@]} -eq 0 ] && { echo "no available browsers"; exit 0; }

# Iterate in priority order. Stop on insufficient_funds — it's not "busy".
SID=""; NO_FUNDS=0
for s in "${SCHEDS[@]}"; do
  s="${s// /}"; [ -z "$s" ] && continue
  OUT=$(ceki rent --schedule "$s" --mode "$MODE" 2>&1)
  SID=$(printf '%s' "$OUT" | jq -r '.session_id // empty')
  [ -n "$SID" ] && { echo "rented $s → $SID"; break; }
  printf '%s' "$OUT" | grep -qiE "insufficient" && { NO_FUNDS=1; break; }
done

[ "$NO_FUNDS" = 1 ] && { echo "insufficient funds — top up wallet, do NOT retry"; exit 0; }
[ -z "$SID" ] && { echo "all browsers busy — report, do NOT loop"; exit 0; }

# Now drive the session
ceki navigate $SID https://example.com
ceki snapshot $SID -o /tmp/state.png

# ... do the work ...

ceki stop $SID

---

Text input — ALWAYS ceki type --natural

Rule: fill every field via ceki type "text" --natural. Real keystrokes (Input.dispatchKeyEvent) — not CDP value-setter. This is the only reliable path that triggers framework state (React _valueTracker, Vue v-model).

Input modes

Why type --natural beats CDP value-setter

• ceki type (any flag) sends real keydown/keypress/keyup events. React fires _valueTracker, Vue catches input event — the field genuinely fills like a human typed.
• Runtime.evaluate el.value = "x" puts text on screen but does NOT trigger framework state. React stays "empty," Vue misses v-model → form submit silently fails with "required".
• --natural adds human jitter between keystrokes — more realistic interaction pattern.

Sequence: CLI → CDP read → CDP input → CDP value-setter

# 1. TRY THIS FIRST — ceki type (real keystrokes through native channel)
ceki type $SID "myusername" --natural

# 2. If field didn't accept keystrokes — blur to trigger validation
ceki cdp $SID --method Runtime.evaluate \
  --params '{"expression":"document.activeElement?.blur()","returnByValue":true}'

# 3. Still stuck? Try CDP Input.insertText (same Input.* channel as real typing)
ceki cdp $SID --method Input.insertText \
  --params '{"text":"myusername"}'

# 4. LAST RESORT — CDP value-setter (only for ProseMirror/Slate/Quill/Lexical rich editors)
#    where Input.* can't write because the editor uses a custom contenteditable overlay
ceki cdp $SID --method Runtime.evaluate --params '{
  "expression": "(function(){var el=document.querySelector(\"textarea[name=body]\");if(!el) return;var s=Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype,\"value\").set;s.call(el,\"\");el.dispatchEvent(new Event(\"input\",{bubbles:true}));el.dispatchEvent(new Event(\"change\",{bubbles:true}));el.blur();return \"ok\";})()",
  "returnByValue": true
}'

Gate for step 4: use ONLY if steps 1-3 all failed. For ordinary / — steps 1-2 always suffice.

When you MUST blur after type

Fields with async validation (username availability, promo codes) validate on blur/debounce. After type:

ceki type $SID "username" --natural
ceki cdp $SID --method Runtime.evaluate \
  --params '{"expression":"document.activeElement.blur()","returnByValue":true}'

CDP value-setter — LAST RESORT only

Only for non-standard rich editors (ProseMirror, Slate, Quill, Lexical) where type physically can't write.

cdp $SID --method Runtime.evaluate --params '{
  "expression": "(function(){var el=document.querySelector(\"textarea[name=body]\");var s=Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype,\"value\").set;s.call(el,\"\");el.dispatchEvent(new Event(\"input\",{bubbles:true}));el.dispatchEvent(new Event(\"change\",{bubbles:true}));el.blur();return \"ok\";})()",
  "returnByValue": true
}'

Gate: use ONLY if ceki type + blur didn't work. For ordinary / — NEVER, type works there.

---

Native vs CDP — knowing which is which prevents lost work

The CLI splits operations into native (high-level — the relay bridges to the provider) and CDP (ceki cdp — raw Chrome DevTools Protocol over the same session). These are different channels.

CDP no_session ≠ rental ended

ceki cdp $SID --method Runtime.evaluate ... can return no_session while the rental itself is alive. The CDP channel is separate from the native session — its timeout/drop does NOT finish the rental.

Don't interpret CDP no_session as "the browser died." Check liveness via native commands:

ceki snapshot $SID -o /tmp/probe.png   # returns JSON with ts → session is alive
ceki my-browsers                       # shows your active rental
ceki sessions                          # your active sessions

If native also returns session_not_found (exit 3) — yes, the rental is over. A CDP error alone — no.

---

CLI reference

Subcommands

Exit codes

Errors go to stderr as JSON: {"error":"...","code":"..."}.

Lifecycle

rent ──► {session_id} ──► navigate/snapshot/click/type/... ──► stop

Each command is a separate subprocess. State between commands is held by resume: the relay keeps the session entry until explicit finish. After RELAY_RESUME_GRACE_MS=-1 the agent disconnect does NOT finish the session.

Session ends ONLY on: user_stop (provider pressed Stop), agent_end (you called ceki stop), provider_offline (browser lost network), insufficient_funds (balance ran out).

Stop is mandatory. Without it the meter keeps ticking.

---

Chat with the host

Each rental has a chat topic. Use it for human-in-the-loop testing: OTP/2FA codes from the host, CAPTCHA resolution for test environments, or confirmations before test payments.

# Send a message
ceki chat $SID send "Can you tell me the 6-digit code from your phone?"

# Wait for reply (up to 120s)
ANSWER=$(ceki chat $SID next --timeout=120 | jq -r .text)
[ "$ANSWER" = "null" ] && echo "no answer in time"

chat history vs chat next — two different operations

Pattern: use history for catching up after a resume (no side effects). Use next for blocking wait on a new reply.

---

Rate limits — DON'T BE RUDE

Real-world incidents: agents hitting rate limits, then retrying in loops, making it worse. Follow these rules.

Rent rate limit: 20/hour per token

• 20 ceki rent calls per hour per account. On the 21st → rate_limit error.
• The counter resets on the UTC hour. Non-sliding window.
• Each ceki stop + ceki rent cycle counts as 2 attempts. Plan long sessions instead of stop+rent per site.

Rate limit recovery — do NOT retry in loops

A tight polling loop on rent is the fastest way to block your token for 60+ minutes.

# When rent returns rate_limit:
# 1. STOP all retries immediately
# 2. Wait ≥10 minutes, or switch to a different token
# 3. Check remaining limit:
curl -s -H "Authorization: Bearer $CEKI_API_KEY" \
  https://api.ceki.me/api/browsers?limit=1 | jq '.meta'

Never write until ceki rent ... done loops. Each rate-limited attempt resets the monitoring window. A loop that hits rate_limit once will keep hitting it — the window only expands.

Other limits

• CDP: 500 commands / 60s per session (command_rate_limit). ceki type --natural sends all keystrokes as ONE packet (plugin/413) — doesn't hit this limit.
• Browser exclusivity: one active rental per browser_id at a time. "Browser is currently in use" means someone else has it — don't retry, pick another or wait.

---

Error handling — read stderr, check exit code

Distinguish real errors from "not available"

---

Important patterns

Session persistence — export/import profiles

Each rental is a fresh incognito tab. To preserve login state across rents, export cookies + fingerprint:

ceki profile $SID export -o /tmp/profile.json
# Next rental:
SID=$(ceki rent --schedule $N --fingerprint-from /tmp/profile.json | jq -r .session_id)
ceki navigate $SID "https://site.com"
ceki profile import $SID -i /tmp/profile.json

Testing CAPTCHA behaviour

When testing your own sites that use CAPTCHA, be aware that a fresh incognito browser has no Google cookies — which can affect CAPTCHA scoring and the challenge type served. This is useful to understand when debugging CAPTCHA-related behaviour on your own site:

ceki navigate $SID https://www.youtube.com; sleep 7
ceki navigate $SID https://www.google.com; sleep 2
ceki click $SID 640 280
ceki type $SID "test query" --natural
# press Enter via CDP
ceki cdp $SID --method Input.dispatchKeyEvent --params '{"type":"keyDown","key":"Enter"}'
sleep 10
ceki navigate $SID https://target-site.com

This sequence builds Google cookie history so you can observe how CAPTCHA behaviour changes — useful for testing your own site's CAPTCHA configuration.

---

Behavioural profiles — profiles/

The skill ships with a library of behavioural profiles in profiles/. These are JSON descriptors that shape any input timing — typing speed, scroll rhythm, mouse trajectory, click delays — to simulate different user demographics and platform-specific interaction patterns. Use them for realistic QA testing across a range of user personas.

Demographic profiles

Each profile represents a user demographic with distinct interaction characteristics. Pass the filename (without .json) as a human preset to the SDK.

And 13 more: creative-professional, freelancer, gamer, middle-aged-male/female, night-shift-worker, parent, rural-user, senior-male/female, social-media-power-user, student-highschool, teen-boys/girls, urban-professional-male/female.

from ceki_sdk import Browser, HumanProfile

# Load a preset
profile = HumanProfile.load_preset("tech-worker-25-40")

async with Browser(token="...", human=profile) as br:
    await br.session(mode="incognito")

Domain profiles

Each domain profile encodes the interaction patterns of a specific platform — scroll depth, reading pauses, click targets, login flow, and CSS selectors.

Each domain profile includes platform_specific data:

{
  "requires_login": true,
  "login": { "pre_login_pause_ms": 1500, ... },
  "selectors_css": {
    "like_button": "[data-testid='like']",
    "tweet_cell": "[data-testid='cellInnerDiv']"
  },
  "sequence_hint": "navigate timeline → scroll 3-5 passes → pause → like | reply → scroll more"
}

Use these as reference when scripting for a specific platform — the selectors and sequence hints give you the DOM targets and interaction order without reverse-engineering each site.

These are reference profiles for scripting platform-specific interactions — the selectors and sequence hints give you the DOM targets and interaction order without reverse-engineering each site.

Pacing profiles (extension-side)

Separate from the human profiles above, pacing profiles control the post-navigation pause the browser extension inserts before the first interaction — critical for realistic user simulation in QA testing.

Set via SDK:

async with Browser(token="...") as br:
    async with await br.session(
        mode="incognito",
        pacing_profile="aggressive"  # ← extension adds 3-7s read before first action
    ) as s:
        ...

Browser search data

When you ceki search, each result includes rich metadata for picking the right browser:

{
  "schedule_id": 12345,
  "geo": "US",
  "language": "en",
  "rating": 4.8,
  "price_per_min": 0.03,
  "domain_allowed": ["*"],
  "allowed_domains": null,
  "online": true,
  "skills": ["scraping", "captcha"]
}

Filter with --filter:

ceki search --limit 10 --filter geo=US --filter price_per_min<=0.05

Available filters: geo, language, price_per_min, rating, online, profile_mode, allowed_domains.

---

Environments — dev vs prod

---

Session modes

---

Detailed reference

• reference/methods.md — full JSON-RPC method reference
• reference/pricing.md — pricing details
• examples/ — quickstarts (Python, TypeScript, IDE configs) and full examples