velox-automation
v2.6.1
Published
Browser automation at terminal velocity. Zero dependencies, any installed Chrome/Chromium/Edge/Brave over CDP or no browser at all. Playwright-compatible API with coherent stealth profiles, human behaviour, Cloudflare/Akamai/PerimeterX/Arkose handling, ac
Maintainers
Readme
Works with Chrome, Chromium, Edge, Brave, Vivaldi, Opera, chrome-headless-shell — or skips the browser entirely when a page doesn't need one.
Coherent stealth fingerprints · human-like behaviour · Cloudflare/Akamai/PerimeterX awareness · extensible to the core
Why velox exists
Every mainstream automation stack makes the same two mistakes: it downloads its own browser whether you need one or not, and it drags dozens of dependencies along for the ride. Velox is a from-scratch rethink (no Playwright/Puppeteer code, zero npm dependencies, ~6.5k lines):
| | playwright | puppeteer | velox | |---|:---:|:---:|:---:| | npm dependencies | 50+ | 10+ | 0 | | downloads a browser on install | ~300 MB | ~150 MB | never | | static pages launch a browser | always | always | no — pure HTTP (~2 ms) | | works with your installed browsers | its own build only | its own build only | any CDP browser | | default transport | pipe | websocket | pipe (+ ws for remote) | | round-trips per selector action | 1–3 | 1–3 | exactly 1 | | batch extract, 3 elements (median) | 26 ms | — | 1 ms | | bundle size | megabytes | megabytes | ~180 KB source |
The speed comes from architecture, not micro-optimization — see how it works.
The 60-second tour
import velox from 'velox-automation';
// ① Open a URL. No browser launches unless the page needs JavaScript.
const page = await velox.open('https://example.com');
console.log(page.engine); // 'lite' — pure HTTP fetch + our own HTML parser
console.log(await page.text('h1')); // "Example Domain"
// ② Browser-only operations escalate transparently (cookies carry over).
const png = await page.screenshot({ full: true });
console.log(page.engine); // 'cdp' — a browser spun up on demand
await page.close();
// ③ Full power mode: your installed Chrome/Edge/Brave, full Playwright surface.
const browser = await velox.launch(); // auto-discovers any CDP browser
const p = await browser.newPage({ stealth: true, ads: true });
await p.goto('https://news.ycombinator.com');
const titles = await p.extract('.titleline > a', { text: true }); // ONE round-trip
await p.getByRole('link', { name: 'More' }).click();
await browser.close();Installation
npm i velox-automation # https://www.npmjs.com/package/velox-automation
# or straight from the repo
npm i github:loak7993-code/veloxPublished package: velox-automation — 146 kB packed, no install scripts, no dependencies.
Node ≥ 20 (22+ recommended — uses the native WebSocket). No postinstall, no
browser download. Velox finds what's already on the machine:
npx vlx detect # lists every Chromium-family browser it can drive…or pin one with VELOX_BROWSER=/path/to/chrome, the executablePath option,
or connect remote: velox.connect('ws://browser-host:3000').
How it works
velox.open(url)
│
┌───────────────┴───────────────┐
│ engine: 'auto' │
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ fetch HTML │ static? │ CDP browser │
│ (own HTTP/1.1, │───────────▶│ any binary, │
│ keep-alive,br, │ │ pipe transport │
│ cookie jar) │ needs JS? │ in-page engine │
└─────────────────┘───────────▶└──────────────────┘
▲ ▲
engine: 'lite' engine: 'cdp'
(never a browser) (or forced with --js)- In-page engine. A ~8 KB selector/wait core is injected once per document.
Finding, waiting, extracting, click-pointing — all execute inside the page.
Every action is exactly one pre-serialized
Runtime.evaluate. No protocol conversations, no stale handles. - MutationObserver waits. Elements resolve the instant the DOM mutates — no polling over the wire. Waiting on a node that appears after 700 ms: 635 ms vs Playwright's 787 ms.
- CDP over stdio pipes (
--remote-debugging-pipe) — lower per-command latency than WebSocket. Automatic fallback;connect()uses WebSocket. - The lite engine. A from-scratch HTTP client (keep-alive, gzip/brotli, redirects, cookie jar) plus a from-scratch HTML parser with CSS-subset selectors. Static pages cost ~2 ms and zero browser processes.
- Browser-native blocking.
ads: truemaps toNetwork.setBlockedURLs— trackers die inside the network stack, pages load lighter and faster. - Zero handles, zero staleness. Locators re-resolve on every call — elements are always current, never detached, never leaked.
Benchmarks
Same binary (chrome-headless-shell 154), same box, 10 runs, medians —
reproduce with node test/bench.js 10:
| operation | velox | playwright-core | |
|---|---:|---:|:---:|
| batch extract (3 elements) | 1 ms | 26 ms | 26× |
| second navigation | 13 ms | 39 ms | 3.0× |
| fill + click + submit | 45 ms | 74 ms | 1.64× |
| 10× title() | 18 ms | 24 ms | 1.33× |
| waitForSelector (700 ms delay) | 635 ms | 787 ms | 1.24× |
| browser close | 26 ms | 34 ms | 1.31× |
| browser launch | 66 ms | 70 ms | 1.06× |
| goto + DOMContentLoaded | 21 ms | 22 ms | 1.05× |
| full-page screenshot | 56 ms | 49 ms | 0.88× |
| lite engine (no browser at all) | ~2 ms/page | — | — |
Feature tour
The auto engine
velox.open(url); // auto: HTTP first, browser only if JS is needed
velox.open(url, { engine: 'lite' }); // never launches a browser
velox.open(url, { engine: 'cdp' }); // always a browser
velox.open(url, { js: true }); // force the browser pathEscalation heuristics: SPA shells (<div id="root"> + scripts, no SSR state),
challenge pages, empty-body + heavy-script pages, meta-refresh loops. Calling a
browser-only op (click, screenshot, eval, …) on a lite session upgrades it
transparently, with cookie state carried over.
Selectors
One syntax everywhere — page, locators, block(), the CLI:
| selector | matches |
|---|---|
| div.card > a | plain CSS (default) |
| text=Sign in · text*=sign · text^=Sign · text$=in · text==Exact | text (substring CI / anchored / exact) |
| role=button · role=button@Sign in · role=button@=Exact | ARIA role + accessible name |
| label=Email · placeholder=Search · alt=Logo · title=Close | form labeling semantics |
| testid=submit | data-testid (configurable via testIdAttribute) |
| xpath=//a[@href] · id=main · tag=div · nth=3 | the classics |
| #host >> button.cta | >> pierces shadow roots and same-origin iframes |
| button:visible · a:has-text("read more") | filters |
Locators — the full Playwright surface
const btn = p.getByRole('button', { name: 'Subscribe' });
const row = p.getByTestId('row-7').filter({ hasText: 'velox' });
await btn.click(); // trusted mouse input, auto-waited
await p.getByLabel('Email').fill('[email protected]');
await p.locator('#agree').check();
await p.locator('#country').selectOption({ label: 'Chile' });
await p.locator('li').nth(2).dragTo('#bin');
await row.isVisible(); // …isChecked/isDisabled/isEditable/isHidden
await row.boundingBox(); // …text/attr/html/val/count/allTextContents
await row.ariaSnapshot(); // '- button "Subscribe"'first() / last() / nth(i) / filter({hasText, has}) / all() / locator(sel) —
every method is one fresh round-trip; nothing goes stale.
Network
// capture (headers, POST bodies, timing, IPs, redirect chains)
p.on('response', (e) => console.log(e.response.status, e.url));
// intercept & mock
p.route('**/api/**', (req) => req.fulfill({ body: '{"n":42}', contentType: 'application/json' }));
p.mock('**/stats', { status: 204 });
// inspect-then-modify through the real server
p.route('**/api/data', async (req) => {
const real = await req.fetch(); // server-side fetch w/ page cookies
req.fulfill({ body: real.body.replace('world', 'proxied') });
});
// block at the network stack + HAR export
await p.block(['doubleclick.net', '*hotjar.com']);
const har = await p.har({ withBodies: true });
// offline / throttling / basic auth
await p.setOffline(true);
await p.emulateNetwork({ latency: 200, downloadThroughput: 1.5 * 1024 * 1024 });
const ctx = await browser.newContext({ httpCredentials: { username, password } });
// wait for traffic
const [req] = await Promise.all([p.waitForRequest('**/api/x'), p.click('#go')]);page.on('websocket') tracks WS frames/headers/close; page.on('worker') and
browser.on('serviceworker') cover web + service workers.
Contexts & sessions
const ctx = await browser.newContext({ // isolated cookie world
baseURL: 'https://api.example.com',
storageState: 'state.json', // Playwright-format state
httpCredentials: { username: 'u', password: 'p' },
serviceWorkers: 'block', bypassCSP: true,
testIdAttribute: 'data-test',
});
await ctx.storageState('state.json'); // save cookies + localStorage
const r = await ctx.request.post('/login', { data: { user, pass } }); // shares the cookie jar
await ctx.close();
// persistent profile: logins & extensions survive restarts
const profile = await velox.launchPersistentContext('./my-profile');Emulation & stealth
await p.emulate('iphone_15'); // 10 device presets
await p.setGeolocation({ latitude: -33.86, longitude: 151.20 });
await p.emulateMedia({ colorScheme: 'dark', media: 'print' });
await p.clock.setFixedTime('2024-06-01T10:00:00Z');
await p.clock.fastForward(60_000); // virtual timers fire instantly
const s = await b.newPage({ stealth: true }); // webdriver, WebGL, plugins,
// window.chrome, languages, …Capture
await p.screenshot({ full: true, mask: ['#ad'], animations: 'disabled' });
await p.pdf({ format: 'A4', margin: { top: 0.5 } });
await p.video.start({ path: 'rec.gif' }); await p.wait(500);
const gif = await p.video.stop(); // animated GIF, own encoder
await p.accessibility.yaml(); // aria tree
await p.coverage.startJSCoverage(); /* … */ await p.coverage.stopJSCoverage();
const ctx2 = b.defaultContext();
await ctx2.startTracing({ screenshots: true }); // chrome://tracing-loadable
await ctx2.stopTracing('trace.json');Video uses a from-scratch pipeline — PNG decode → median-cut palette → LZW — because a zero-dependency library shouldn't need ffmpeg.
Scaling
const pool = new velox.Pool({ browsers: 4, pagesPerBrowser: 4, pageOpts: { ads: true } });
const titles = await pool.map(urls, (u, page) =>
page.goto(u, { waitUntil: 'interactive' }).then(() => page.title()),
{ concurrency: 16 });
await pool.close();Static pages never touch the pool — the auto engine fetches them in-process.
Assertions
import { expect } from 'velox-automation';
await expect(p.getByRole('heading')).toHaveText('Example Domain');
await expect(p.locator('li')).toHaveCount(3);
await expect(p).not.toHaveTitle('Wrong');
// toBeVisible/Hidden/Enabled/Disabled/Checked/Editable,
// toContainText/toHaveValue/toHaveAttribute/toHaveURL/toHaveCookiePolling assertions with .not — pair them with any test runner.
Speed
Everything below is measured by npm run speed (same machine, medians):
| | before | v2.3 | |
|---|---:|---:|---:|
| newPage() (with spare: 2) | 29 ms | 2 ms | 14.5× — opt-in warm renderers |
| launch() handoff (prewarmed) | 64 ms | ~0 ms | velox.prewarm() keeps browsers ready |
| 4 data actions | 2 ms | 1 ms | 2× — page.batch() flies them in one flush |
| 24 latency-bound pages | 749 ms | 73 ms | 10.3× — fetchAll(), no browser at all |
| 12-page scrape workflow | 44 ms | 33 ms | 1.33× — less setup per page |
| navigate + ready-to-read | 17 ms | 16 ms | waitUntil: 'none' + waitForSelector |
| viewport screenshot | 50 ms | 48 ms | fast: true |
// launch a browser and pre-build pages off the critical path
await velox.prewarm({ browsers: 1, pagesPerBrowser: 6 });
const browser = await velox.launch(); // hands back the warm browser instantly
const page = await browser.newPage(); // ~2 ms — a blank renderer was waiting
// per-browser control — opt-in, because background renderers can misbehave on
// constrained runners; the default path stays maximally predictable
await velox.launch({ spare: 4 }); // keep 4 warm renderers for burstsAlso in the fast path: the in-page engine ships compacted (25 KB → 22 KB per page), page setup is single-flight (the auto-attach race used to run it twice), engine injection is lazy (first use, and it self-heals), download plumbing arms only when a listener appears, and headless launches skip the GPU entirely.
Bandwidth
Most automation bandwidth is spent on bytes you never read. velox makes that a first-class, measurable knob — profiles, size caps, third-party filtering and a conditional-GET cache.
const page = await b.newPage({ bandwidth: 'text-only' }); // documents only
await b.newPage({ bandwidth: 'lean' }); // also blocks images/fonts/media
await b.newPage({ bandwidth: { block: ['image', 'media'], maxBytes: 1_000_000, blockThirdParty: true } });
await page.setBandwidth('minimal'); // switch at runtime
const bw = page.transferred(); // { total, byType, blocked, profile } — measured, not estimated
page.on('blocked', (e) => console.log(e.reason, e.url)); // "type:Image", "third-party:Script", "oversize:Media"Measured on a 125-resource test page (node test/bandwidth.js):
| profile | transferred | requests blocked | vs full |
|---|---:|---:|---:|
| full | 473.8 KB | 0 | — |
| lean | 5.6 KB | 121 | 99% less |
| minimal | 5.6 KB | 121 | 99% less |
| text-only | 4.8 KB | 122 | 99% less |
The browser-free engine is even cheaper — it only ever downloads the document —
and now keeps a conditional-GET cache (ETag/Last-Modified), so re-fetching
an unchanged page costs a 304 round-trip instead of the whole body:
const cache = velox.createCache({ dir: '.velox-cache' }); // persists across runs
await velox.fetch(url, { cache }); // 200 + stored
await velox.fetch(url, { cache }); // 304 → served from disk
cache.stats; // { revalidated, bytesSaved, ... }
await velox.fetch(url, { cache, ttl: 60_000 }); // skip revalidation entirely for 60 s
await velox.fetch(hugeUrl, { maxBytes: 500_000 }); // abort oversized bodies mid-stream
await velox.fetchAll(urls, { cache, concurrency: 16 }); // one cache, no browserCLI: vlx open <url> --bandwidth text-only --cache-dir .velox-cache
Proxies
Real proxy support at every layer — including the browser-free lite engine, so a scrape can rotate exits without ever launching Chrome.
// one-shot checks: status, latency, exit IP
await velox.checkProxy('socks5://user:pass@host:1080'); // → { ok, status, ms, ip }
// lite engine, no browser
await velox.fetch(url, { proxy: 'http://user:pass@host:8080' });
await velox.fetchAll(urls, { proxy: pool.next().toProxy(), concurrency: 10 });
// browsers: launch-level or per-context (isolated cookie jar + its own exit)
const browser = await velox.launch({ proxy: 'http://user:pass@host:8080' });
const ctx = await browser.newContext({ proxy: { server: 'socks5://host:1080', bypass: ['*.internal'] } });
// rotating pool: strategies, sticky sessions, health checks, automatic ejection
const pool = new velox.ProxyPool(proxies, { strategy: 'least-latency', maxFailures: 3, cooldownMs: 60_000 });
await pool.healthCheck({ url: 'https://example.com', ipUrl: 'https://api.ipify.org' });
const proxy = pool.sticky('account-42'); // same exit for the same key
await pool.withProxy((p) => velox.fetch(url, { proxy: p })); // retries the next healthy exit
pool.stats(); // per-proxy uses/failures/latency/ejectionSupported: http, https, socks4, socks5, with inline or explicit credentials
(user:pass@host), bypass lists, and proxy auth handled through the CDP auth
challenge (source: "proxy") for browsers plus direct Proxy-Authorization for lite.
Or rotate automatically across browsers:
velox.use(velox.plugins.proxyRotate(pool)); // each launch() gets the next exitVerified against a live residential proxy: HTTP + HTTPS (CONNECT/TLS), rotating exit
IPs, browser + context-level routing, and pool ejection. A from-scratch HTTP+CONNECT
and SOCKS5 proxy server ships in test/site/proxy.js so proxying is tested offline too.
Stability
// retry transient failures (dropped sockets, timeouts)
const page = await velox.open(url, { retries: 2, retryDelay: 300 });
// long-running remote browsers: keep the connection alive across drops
const browser = await velox.connect('ws://remote:9222', { autoReconnect: true });
browser.on('reconnected', ({ attempt }) => console.log('back after', attempt));
await browser.healthy(); // cheap liveness probe
await browser.reconnect(); // manual: re-attaches every existing page objectA reconnected browser keeps the same page objects working — sessions are
re-attached, init scripts and route interception re-armed — instead of forcing you
to rebuild state. Also: velox.open retries only transient errors (never a 404),
a dropped CDP link raises a clear error instead of a silent hang, and a sandbox
failure self-heals (see the FAQ).
Customisation
// global defaults, also loadable from $VELOX_CONFIG (JSON) or VELOX_* env vars
velox.config({ timeout: 20000, engine: 'auto', proxy: 'socks5://host:1080', retries: 1, ads: true });
// plugins: hook any stage of the lifecycle
velox.use({
name: 'my-plugin',
pageOptions: (o) => ({ ...o, headers: { ...o.headers, 'x-team': 'scraping' } }),
onPage: (page) => page.on('pageerror', (e) => console.error(e.text)),
});
// built-in plugins
velox.use(velox.plugins.stealth());
velox.use(velox.plugins.adblock());
velox.use(velox.plugins.blockImages()); // skip images/fonts/media — big speed win
velox.use(velox.plugins.humanize()); // human-ish typing + cursor paths
velox.use(velox.plugins.retry(2));
velox.use(velox.plugins.logger({ requests: true }));
velox.use(velox.plugins.proxyRotate(pool));
// your own selector syntax, evaluated inside the page
await page.addSelectorEngine('priceabove', (value, root) =>
[...root.querySelectorAll('[data-price]')].filter((el) => +el.dataset.price > +value));
await page.count('priceabove=25'); // works with >> chains, waits and extract too
await page.text('section.box >> priceabove=25');
// your own device preset
velox.registerDevice('pixel_9', { width: 412, height: 915, dsf: 2.6, mobile: true, ua: '…' });CLI:
vlx check-proxy 'http://user:pass@host:8080' --ip https://api.ipify.org
vlx open example.com --proxy socks5://127.0.0.1:1080 --retries 2
vlx open example.com --config ./velox.jsonActing like a real browser
Detectors score coherence and behaviour far more than any single value. velox ships profile-driven fingerprints where every surface agrees, plus human interaction.
await b.newPage({ stealth: true }); // coherent defaults
await b.newPage({ stealth: { profile: 'chrome-windows', geo: 'de-DE' } });
// every value in one profile agrees: UA ↔ Client Hints ↔ platform ↔ WebGL ↔
// screen ↔ languages ↔ timezone ↔ locale ↔ fonts| profile | platform | UA-CH | WebGL | timezone |
|---|---|---|---|---|
| chrome-linux | Linux x86_64 | Linux 6.6.0 | Intel UHD 630 / ANGLE D3D11 | America/New_York |
| chrome-windows | Win32 | Windows 15.0.0 | NVIDIA GTX 1660 SUPER | America/Chicago |
| chrome-mac | MacIntel | macOS 14.5.0 | Apple M1 Pro / Metal | America/Los_Angeles |
| chrome-android | Linux armv8l | Android 14 | Adreno 740 | America/New_York |
geo: 'de-DE' rewrites locale, timezone and Accept-Language together (15 presets) —
a German IP with en-US and America/New_York is a contradiction, and that is what
actually gets you flagged.
Hardened surfaces: navigator.webdriver, plugins/mimeTypes with correct prototypes,
window.chrome (runtime/app/csi/loadTimes), permissions ↔ Notification.permission,
WebGL vendor/renderer + debug-renderer consistency, canvas & audio noise that is
seeded and stable (two reads of the same canvas agree — a mutating patch is itself a
tell), Function.prototype.toString so patched builtins still report [native code],
outerWidth/outerHeight coherence with the viewport, userAgentData (UA-CH) including
getHighEntropyValues, WebRTC leak blocking, enumerateDevices, battery, connection.
// human-like interaction — what behavioural scoring actually measures
await page.human.click('#login'); // curved approach, dwell, hold
await page.human.type('#email', '[email protected]'); // per-key cadence, word pauses, rare corrections
await page.human.scroll({ by: 900, read: true }); // wheel momentum + reading pauses
await page.human.idle(2000); // small drift movements
await page.human.readText('article', { wpm: 220 }); // believable reading beatCloudflare · Akamai · PerimeterX
Detect, wait for and engage bot-management challenges — with an honest report of what happened. Mock vendor pages ship in the test suite so this is verified offline.
await page.goto(url);
const info = await page.challenge.detect();
// { vendor: 'cloudflare', challenged: true, cleared: false, signals: ['header:cf-mitigated', …] }
// navigate *through* a challenge: waits, engages (Turnstile checkbox, PX press-and-hold,
// interstitial verify button), then retries once clearance lands
const { response, challenge } = await page.challenge.goto(url, { human: true, timeout: 45000 });
console.log(challenge.outcome); // { vendor, cleared: true, acted: ['turnstile-click'], ms: 1500 }| vendor | detected by | engaged how |
|---|---|---|
| Cloudflare | cf-mitigated, cf-ray, /cdn-cgi/challenge-platform/, Turnstile iframes, cf_clearance | human-click the Turnstile checkbox, wait for clearance, re-navigate |
| Akamai | _abck, bm_sz, /akam/ sensor scripts, Access Denied/Reference # | let the real sensor run against a clean environment, wait for _abck |
| PerimeterX | _px, _pxhd, px-cloud.net, #px-captcha | press-and-hold with jitter for ~10s, wait for _px3 |
| DataDome | datadome, x-datadome | wait for clearance |
Verified offline against mock challenge pages in test/site/:
baseline (no stealth): 46/71 checks (65%) ← a bare browser is detected
with stealth: 71/71 checks (100%) ← every vector closed
Cloudflare mock: detected → Turnstile clicked → cf_clearance → reached the gated page
Akamai mock: detected → sensor ran → _abck issued
PerimeterX mock: detected → press-and-hold → _px3 issuedWhat this cannot do (read this before filing an issue):
- IP reputation is decisive. Datacenter/VPN ranges are blocked regardless of how
clean the fingerprint is. Use residential or mobile exits (
velox.ProxyPool) that match the profile's geo — ade-DEprofile needs a German exit. - Image/audio CAPTCHAs are not solved. That requires a human or a solving service.
- Vendor sensor payloads are not forged. We run the real scripts in a clean
environment; forging
_abck/_pxpayloads is out of scope by design. - Use a real browser for hard targets.
chrome-headless-shellis a stripped build; for Cloudflare's managed challenge prefer full Chrome with--headless=newor headed (vlx detectshows what you have,VELOX_BROWSERpins it). - Warm, persistent profiles (
launchPersistentContext) age better than fresh ones.
Field helpers
Shaped by real use against anti-bot-heavy targets (Amazon, Bright Data + Turnstile, Arkose/AWS-WAF flows) — the loops that get written over and over:
// wait for a captcha token field to populate. On timeout it tells you WHICH state it
// died in ("script never loaded" vs "widget present but token field missing"), instead
// of a silent null. It does not solve the puzzle — it removes the boilerplate.
const token = await page.waitForCaptchaToken('input[name="cf-turnstile-response"]', { timeout: 60000 });
// what widget is actually here? (prefix-matches dynamic ids like turnstile_container_6243…)
const w = await page.detectChallenge();
// { type: 'turnstile', sitekey: '0x4AAA…', iframeUrl: 'https://challenges.cloudflare.com/…',
// containerId: 'turnstile_container_6243920994991472', visible: true, tokenPresent: false }
// responses with bodies, and a filtered network log
const resp = await page.waitForResponse(/checkout\/.*\/pay/);
const json = await resp.json(); // .text() / .body() / .status / .headers
const xhr = page.netlog(/api|checkout|auth/); // → [{ method, status, url, postData, json() }]
// one call → the whole forensic bundle (DOM, network, console, pageerrors, storage, screenshot)
const dump = await page.debugDump('velox-debug');
// → <dir>/{page.html,network.json,bodies.json,console.log,errors.log,cookies.json,storage.json,shot.png,summary.json}
// flaky residential proxies are the normal case, not the exception
await page.gotoWithRetry(url, { retries: 4, backoff: 400, onAttempt: (a, e) => log(a, e) });
await page.human.warmup({ mouse: 3, scroll: 1, dwellMs: 900 }); // look alive before touching anything
await page.human.hold('#px-captcha', { ms: 10000 }); // press & hold with tremor (PX)
await page.cdp('Network.setBlockedURLs', { urls: ['*ads*'] }); // raw CDP one-linerCookie hand-off for HTTP + browser hybrids — the classic silent bug is a cookie
whose domain lacks the leading dot (amazon.com), which then never matches
www.amazon.com. All importers normalise, dedupe and report what they dropped:
velox.importSession(cookieArray); // or a curl header, or a HAR file
await velox.fetch(...) → browser takes over:
const page = await b.newPage(); // the pending session lands on first navigation
await page.importSession(cookies); // or explicitly, on a live page
await page.importCurl('cookie: session=abc; theme=dark', { domain: 'shop.example.com' });
await page.importHAR('capture.har', { urlFilter: 'shop.example.com' });
const state = await page.exportSession(); // Playwright-compatible storage state
velox.normalizeCookies(cookies);
// → { cookies: [...dotted, deduped, path-normalised], skipped: [{ cookie, why }], dropped: 1 }page.eval() returns real values — objects and arrays come back as JSON, function
strings are called, and anything that cannot cross the wire raises an explicit error
rather than a silent {}:
await page.eval('Object.keys(window.turnstile)'); // ['render','reset']
await page.eval('() => document.body.innerText'); // 'hello' (function-as-string works)
await page.eval((n) => n * 2, 21); // 42
await page.eval('document.body');
// ✗ page.eval(): value is a DOM node (<body>) — read a property (textContent, value…)
// or use page.$()/extract()For extracting page data, prefer extract() — it batches N elements × M fields in a
single round-trip and never surprises you:
await page.extract('.product', { text: true, attrs: ['data-sku', 'href'], html: false });
await page.tables(); await page.meta(); await page.jsonld(); await page.readable();Account-creation scoring (onboarding / new-account fraud controls)
Signup risk engines score five families of signal. velox gives you a handle on each one, and reports the score and the exact reasons the target returned — so a run tells you which signal to fix instead of leaving you guessing.
| family | what the engine looks at | what velox does |
|---|---|---|
| fingerprint coherence | UA ↔ Client Hints ↔ platform ↔ WebGL ↔ screen ↔ tz | stealth profiles (4 platforms, version-aligned to the real binary) |
| identity coherence | phone country ↔ address ↔ postal format ↔ name ↔ email ↔ age | velox.identity — generates and validates (catches planted contradictions) |
| behavioural regularity | keystroke/pointer interval variance, click presence, time-to-first-input, paste | page.human.* + velox.behaviouralRegularity() to measure it |
| cross-account linkage | shared device fingerprint, cookie values, storage keys | a fresh context per account + runner.verifyIsolation() proof |
| velocity | N accounts per exit/device per window | paceMs, maxPerHour, per-account proxy rotation |
const id = velox.identity.generate({ country: 'DE', seed: 7 });
// { fullName: 'Lukas Wagner', email: '[email protected]', phone: '+49 30 5550062',
// address: { city: 'Hamburg', region: 'Hamburg', postalCode: '22765', country: 'Germany' },
// locale: 'ja-JP'→'de-DE', timezone: 'Europe/Berlin', dob, password, device: {...},
// coherence: { ok: true, issues: [] } }
velox.identity.check({ ...id, phone: '+1 202-555-0123' });
// → { ok: false, issues: [{ field: 'phone', why: '+1 202-555-0123 is not a DE number (expected +49)' }] }
velox.identity.stealth(id); // the matching browser environment (locale+tz+languages+seed)
velox.identity.geo(id); // what the exit IP must be consistent withRun a declarative plan per identity — templated from the identity, executed with human behaviour, in an isolated context:
const runner = new velox.AccountRunner({ browser, paceMs: [900, 2600], maxPerHour: 12 });
const record = await runner.register({
url: 'https://site.example/signup',
identity: velox.identity.generate({ country: 'GB' }),
expect: { selector: '#welcome' },
steps: [
{ fill: '#name', value: '@identity.fullName' },
{ type: '#email', value: '@identity.email', cps: 6 }, // human cadence, not paste
{ fill: '#phone', value: '@identity.phone' },
{ select: '#country', value: '@identity.country' },
{ fill: '#dob', value: '@identity.dob' },
{ waitForCaptchaToken: undefined, optional: true }, // handle the widget if present
{ humanClick: '#submit' },
{ waitFor: '#welcome, #verify, #blocked', optional: true },
],
});
record.risk; // { score: 100, reasons: [], markers: ['x-risk-score: 100'], verificationRequired: false }
record.steps; // per-step ok/ms, so a failing step is named
await runner.farm(plan, { count: 5, concurrency: 1 }); // paced, isolated, rotated exits
runner.verifyIsolation(); // proves accounts aren't linkable
runner.summary(); // one row per account: score, reasons, msVerified against a local risk scorer that implements those five families
(test/accounts.js, 40 checks) — each family has a control case:
naive automation → 403, score 0, 16 reasons (automation + identity + behaviour)
identity+stealth+
human behaviour → 201, score 100, 0 reasons, account created
same context reuse → 2nd attempt flagged as the same device
fresh contexts → isolation proof clean, no shared cookie values
rapid fire → velocity flagged on the 4th signup from that exit
paced run → no velocity flag
scripted typing → machine-likeness 1.0 · human typing 0.0When a website fingerprints you
A site does not fingerprint "the browser" — it hashes a dozen surfaces and concatenates the results into one identifier. Two things follow, and velox handles both:
- within one identity the fingerprint must be stable (otherwise every page load looks like a new device), and
- between identities it must differ on at least one component (otherwise your accounts are one person with many email addresses).
// one coherent device per identity: seed drives every rotating surface together
const ctx = await b.newContext({ stealth: velox.identity.stealth(identity) });
// or drive it directly
const ctx = await b.newContext({ stealth: { profile: 'chrome-windows', seed: 4242 } });What rotates with the seed, and what a site can link on:
| surface | rotates per identity | notes | |---|---|---| | canvas 2D image | ✅ | deterministic per seed; identical on repeat reads | | rendered WebGL image | ✅ | the strongest GPU signal — pixels move, not just the reported renderer | | WebGL renderer/vendor | ✅ | pool of 30 real cards; never a software rasteriser (SwiftShader/llvmpipe are VM tells) | | WebGL limits + extension order | ✅ | driver-version-like variance per identity | | audio fingerprint | ✅ | | | element geometry (ClientRects) | ✅ | stable sub-pixel jitter per element | | UA / Client Hints / screen / tz / locale | ✅ | version-aligned to the real binary, locale and language never disagree | | fonts | ❌ | text metrics can't be faked without breaking rendering — the one surface that stays shared. Rotating it needs a real font set per platform. | | screen resolution / OS build | via profile | set the profile, not the seed |
Verified on a live third-party page (npm run ipfighter, ipfighter.com): across two
identities, 4 of 5 hashed components differ — canvas, rendered WebGL, audio, element
geometry — and each identity is byte-stable across reloads. Their bot-detection page scores:
| run | score | suspicious signals | failing checks |
|---|---|---|---|
| velox, no stealth | 84% | 8 | webdriver, HeadlessChrome UA, missing window.chrome, 0 plugins, SwiftShader WebGL, … |
| velox, stealth: true | 98% | 1 | chrome.runtime missing — a check a genuine Chromium also fails |
| control: clean Chromium, no velox at all | 90% | 5 | webdriver, HeadlessChrome UA, SwiftShader, 800×600 VM screen, chrome.runtime |
Two of those fixes came directly from that page's own checks:
- Accessor integrity. It reads
Object.getOwnPropertyDescriptor(Navigator.prototype, prop).getand rejects a getter that has an ownprototypeproperty (every function expression does), a non-nativetoString, or a wrongname. velox installs method-shorthand getters namedget <prop>that report[native code]and throwTypeError: Illegal invocationon a foreign receiver — byte-identical to a real WebIDL accessor. - Don't invent surface. Our old shim added
chrome.runtimebecause a detector complained it was missing. A clean Chromium page has{app, csi, loadTimes}and noruntime— so the shim was itself the anomaly. It is now opt-in (stealth: { chromeRuntime: true }).
Tested against real platforms
npm run platforms drives real vendors and npm run ipfighter a real detection +
fingerprinting site (both need network, both skip cleanly offline) and report what they found:
| target | result |
|---|---|
| Cloudflare Turnstile — official demo, test key 1x0000…AA | widget detected (type/sitekey/script/visibility), and the real token is obtained: waitForCaptchaToken() returned a 21-char token |
| hCaptcha — official demo | detected as hcaptcha with iframe URL + sitekey (its reCAPTCHA-compat field is correctly outranked) |
| reCAPTCHA v2 — official demo | detected with sitekey read from the anchor iframe's k= parameter |
| Arkose Labs — real client-api.arkoselabs.com script, public test key | script + container + sitekey identified before the challenge mounts |
| sannysoft bot detector | 0 failed checks |
| ipfighter bot detection | 98% human / 1 suspicious signal (clean Chromium control: 90% / 5) |
| ipfighter browser fingerprint | 4/5 hashed components rotate per identity; fonts stay shared (documented limit) |
Detection is weighted, because real pages are ambiguous: hCaptcha's compat mode also emits
g-recaptcha-response, and Cloudflare mounts Turnstile inside a closed shadow root — so
evidence is scored (script/iframe > container > token field), shadow roots are pierced
where the platform allows it, and the sitekey is read from the widget URL when the
container has no data-sitekey.
Live detector feedback also found and fixed a real fingerprint leak: navigator.webdriver
was patched as an own property of the instance, which sannysoft's “WebDriver (New)”
check reads as automation. All navigator patches are now mounted on Navigator.prototype
(matching a clean browser's descriptor shape), oscpu/standalone (Firefox/iOS-only)
are no longer added, and the local harness scores 78/78 with a descriptor-level check.
Honest limits. creepjs and pixelscan still classify headless mode itself (5 and 8 surface mentions, and roughly the same with a full browser) — that is their purpose and no in-page patch changes it; every fingerprint-level check we control passes. IP reputation still decides the outcome on hostile targets, and an interactive image puzzle needs a human or a solving service. Use this for testing your own onboarding controls and for authorised engagements.
Make it yours
// middleware around EVERY page command: time it, log it, retry it, rewrite arguments
velox.middleware(async ({ page, method, args }, next) => {
const t = Date.now();
const out = await next();
metrics.observe(method, Date.now() - t);
return out;
});
// your own methods on pages, browsers and locators
velox.registerCommand('dismissBanners', async function () {
return this.click('.cookie-accept', { timeout: 800 }).catch(() => {});
});
velox.registerCommand('product', function () { return this.info?.product; }, { target: 'browser' });
// global selector engines: usable as `name=value` on every page, in every frame
velox.registerSelectorEngine('priceAbove', (value, root) =>
[...root.querySelectorAll('[data-price]')].filter((el) => +el.dataset.price > +value));
// extra lifecycle hooks beyond plugins
velox.hook('onNavigation', (page, url) => console.log('→', url));
velox.hook('onChallenge', (page, info) => console.log('challenge:', info.vendor));
page.ext.anything = 'your namespace'; // no collisions with the core
velox.extensions(); // introspect what you have registeredComing from Playwright
| Playwright | velox |
|---|---|
| chromium.launch() | velox.launch() — any installed CDP browser |
| browser.newContext() / options | browser.newContext() — same options, plus engine |
| context.addInitScript, exposeBinding | same names on context |
| page.getByRole/Text/Label/… | identical |
| page.locator().click/check/selectOption/… | identical |
| page.route() + route.fulfill/abort/continue | identical, plus route.fetch() |
| page.request | context.request (shared cookie jar) |
| page.waitForRequest/Response/LoadState/URL/Function | identical |
| page.clock (install/fastForward/…) | identical semantics |
| context.storageState() | identical JSON format — states are portable |
| page.screenshot({ mask, animations }) | identical |
| launchPersistentContext() | velox.launchPersistentContext(dir, opts) |
| page.pdf / video / coverage / accessibility | identical (video = GIF) |
| page.evaluateHandle / elementHandle | identical, plus function-form evaluate(fn, arg) |
| expect(locator).toBe… | velox.expect() — same shape |
| Firefox / WebKit engines | ✗ not supported — they don't speak CDP |
| test runner / trace viewer UI / inspector | ✗ out of scope — use any runner |
Migration is mostly find-and-replace; the object model is deliberately aligned.
CLI
vlx detect # browsers found on this machine
vlx open https://example.com # readable text (auto engine)
vlx open example.com --sel 'h2' --json # specific elements, structured
vlx shot example.com --full -o page.png # full-page screenshot
vlx shot example.com --sel '#chart' -o c.png
vlx pdf example.com -o page.pdf
vlx links example.com --json
vlx scrape example.com --recipe tables --json
vlx eval example.com "document.title"
vlx save-session example.com s.json # cookies + storage
vlx load-session example.com s.json
vlx bench example.com # lite vs browser timings
# global flags
--engine auto|lite|cdp · --js · --browser PATH · --stealth · --ads
--device iphone_15 · --ua · --locale · --tz · --proxy socks5://…
--header "K: V" · --cookie "a=b" · --viewport 1920x1080
--wait SEL · --timeout ms · --headedAPI reference
| export | |
|---|---|
| velox.open(url, opts?) | adaptive session (engine, stealth, ads, device, ua, proxy, headers, routes, timeout, …) |
| velox.scrape(url, {recipe}) | one-shot scrape: all, text, links, images, tables, meta, jsonld |
| velox.launch(opts?) | any installed browser (headless, proxy, args, userDataDir, transport, timeout) |
| velox.launchPersistentContext(dir, opts?) | real profile |
| velox.connect(endpoint) | ws://… or host:port |
| velox.detect() | installed CDP browsers |
| velox.Pool, velox.DEVICES, velox.expect, velox.parseHtml, velox.needsJS | utilities |
| area | methods |
|---|---|
| navigation | goto (waitUntil: none/interactive/load/networkidle/settle), reload, back, forward, setContent, waitForUrl |
| data (1 round-trip each) | title, url, content, text(sel), attr, html, val, count, extract (the workhorse), texts, links, images, tables, forms, meta, jsonld, readable |
| actions | click (position/force/trial), dblclick, hover, type (human jitter), fill, press, check/uncheck/setChecked, selectOption, selectText, dragAndDrop, scrollBy, scrollToBottom |
| waits | waitForSelector (attached/visible/hidden), waitForFunction, waitForLoad, waitForRequest/Response/RequestFinished, waitForEvent/Dialog/Popup/Download, wait |
| input | mouse.move/click/wheel/humanMove (bezier paths), keyboard.press/type/insertText, touch.tap/swipe |
| network | route/unroute/mock/block, requests(), body(entry), har, setHeaders, setOffline, emulateNetwork, cookies/setCookies |
| scripts | eval (fn or string), evaluate, evaluateHandle, elementHandle(s), $eval, $$eval, addInitScript/removeInitScript, addScriptTag/addStyleTag, expose(fn) |
| frames | frameLocator(sel), frames(), inFrame(sel), >> selector piercing |
| emulation | emulate(device), setViewport, setUA, setLocale, setTimezone, setGeolocation, emulateMedia, colorScheme |
| capture | screenshot, pdf, video, coverage, accessibility, clock |
| sessions | localStorage, saveSession/loadSession, cookies |
| events | console, pageerror, dialog, request, response, requestfinished, download, filechooser, websocket, worker, frame, crash, close |
| object | surface |
|---|---|
| Browser | newPage, newContext, defaultContext, pages, close, events popup/worker/serviceworker/frame/target |
| BrowserContext | newPage, route, addInitScript, expose, cookies, storageState, grantPermissions, setOffline, setGeolocation, request, startTracing/stopTracing, newCDPSession, close |
| Download | url, suggestedFilename, finished(), path(), saveAs(), cancel() |
| JSHandle / ElementHandle | evaluate, jsonValue, getProperties, click, boundingBox, $(sel), screenshot |
| Pool | acquire/release/use/map(items, fn, {concurrency}) |
| API | |
|---|---|
| velox.fetch(url, opts?) | keep-alive HTTP, gzip/brotli/deflate, redirects, cookie jar — returns {status, headers, text(), json(), doc} |
| velox.parseHtml(html) | from-scratch parser + CSS-subset DOM (select, selectAll, text, links, tables, readable, …) |
| velox.needsJS(res) | the escalation heuristics, usable standalone |
Testing
146 checks across four suites, no CI browser downloads beyond a stock chrome-headless-shell:
npm test # smoke (37) · lite+auto (27) · pool · playwright parity (82)
npm run bench # head-to-head vs playwright-core, same binary
node examples/tour.mjsCI runs on every push — see the badge above and .github/workflows/ci.yml.
Honest limitations
- Firefox and WebKit are not supported. They don't implement CDP (Firefox removed it; Safari never had it). Everything Chrome-family works.
- Stealth is best-effort surface patching — dedicated detection stacks can still fingerprint a headless environment. Use a full (non-shell) browser and a persistent profile for the most realistic footprint.
- Video records GIF, not mp4 — the deliberate price of zero dependencies.
- The lite engine parses HTML, it doesn't run it — no JS, no client-side rendering, no same-origin iframe DOM (the browser engine handles all of that).
FAQ
vlx detect shows the candidates. Preference order: Chrome → Chromium → Edge →
Brave → Vivaldi → Opera → headless-shell. Snap-wrapped browsers are
deprioritized when a native binary exists (snap confinement breaks some /tmp
behavior). Pin with VELOX_BROWSER, --browser, or executablePath.
Heuristics can be fooled. Force the outcome when you know it:
velox.open(url, { engine: 'lite' }), { engine: 'cdp' }, or upgrade any
session manually with await session.upgrade().
Velox auto-adds --no-sandbox --disable-gpu --disable-dev-shm-usage when the
UID is 0. As a normal user on distros that restrict unprivileged namespaces
(Ubuntu 23.10+, some containers), Chrome refuses to start with
FATAL: No usable sandbox! — velox detects that and relaunches with
--no-sandbox automatically. Force it up front with VELOX_NO_SANDBOX=1
(or velox.launch({ noSandbox: true })) to skip the failed first attempt.
Precedence: executablePath option → browser option → VELOX_BROWSER
environment variable → auto-discovery. So VELOX_BROWSER=/usr/bin/brave-browser
works for every velox.open/velox.launch() call without touching your code.
goto resolves at DOMContentLoaded — the HTTP status arrives with the
response, usually before. With waitUntil: 'none' the navigation returns
before the response lands; read page.status after, or use waitUntil: 'load'.
Chrome bypasses loopback addresses by default (same as Playwright/Puppeteer). To force local targets through a proxy, add it to the bypass list the Chrome way:
proxy: { server: 'http://127.0.0.1:8080', bypass: ['<-loopback>'] }Remote proxies and remote targets are unaffected.
It gives you the two things that matter most — a coherent environment and human-like behaviour — plus challenge detection and engagement:
const page = await b.newPage({ stealth: { profile: 'chrome-windows', geo: 'de-DE' } });
const { challenge } = await page.challenge.goto(url, { human: true });Assessed honestly: a clean-fingerprint browser passes the JS/behavioural layers in most cases (verified at 100% against a 71-vector detector harness), and Turnstile checkboxes / PX press-and-hold are engaged automatically. What decides the rest is IP reputation (use residential exits that match the profile geo), whether the vendor shows an image CAPTCHA (not solvable by software without a solving service), and the target's risk tolerance (banks and some managed challenges will still hold you). Nothing here forges vendor sensor payloads; we run the real scripts in a clean browser. Treat it as "indistinguishable from a careful human on a decent IP", not "bypasses everything".
- Don't use a browser —
velox.fetchAll(urls, { concurrency: 16, cache })for anything static: no renderer, no subresources, ETag revalidation. - If you need JS, prewarm once and reuse:
await velox.prewarm({ browsers: 1, pagesPerBrowser: 8 }), thengoto(url, { waitUntil: 'none' })+waitForSelector(sel). - Trim the page with a bandwidth profile (
text-onlycut a test page from 474 KB to 4.8 KB) and keepcapture: falseunless you need request logs. - Batch independent actions with
page.batch([...])instead of awaiting each.
Measured: a static scrape with fetchAll is ~10× faster than one page per browser,
and a JS-required scrape runs at ~33 ms/page including navigation and extraction.
Yes: page.createCDPSession() (or context.newCDPSession(page)) returns the
live session — send, fire, waitForEvent, all pipelined.
