{"id":48754532,"url":"https://github.com/toolstackhq/cdpwright","last_synced_at":"2026-04-18T10:01:24.047Z","repository":{"id":350790128,"uuid":"1207752890","full_name":"toolstackhq/cdpwright","owner":"toolstackhq","description":"Lightweight Chromium-only browser automation library built on CDP. Playwright-style API — no test runner, no framework baggage.","archived":false,"fork":false,"pushed_at":"2026-04-16T00:10:14.000Z","size":421,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-16T08:03:59.033Z","etag":null,"topics":["automation","browser-automation","cdp","chromium","devtools-protocol","e2e-testing","headless-browser","nodejs","playwright","test-automation","typescript","web-testing"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toolstackhq.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T10:59:47.000Z","updated_at":"2026-04-16T00:10:18.000Z","dependencies_parsed_at":"2026-04-17T09:00:51.892Z","dependency_job_id":null,"html_url":"https://github.com/toolstackhq/cdpwright","commit_stats":null,"previous_names":["toolstackhq/cdpwright"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/toolstackhq/cdpwright","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolstackhq%2Fcdpwright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolstackhq%2Fcdpwright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolstackhq%2Fcdpwright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolstackhq%2Fcdpwright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toolstackhq","download_url":"https://codeload.github.com/toolstackhq/cdpwright/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolstackhq%2Fcdpwright/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31922399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","browser-automation","cdp","chromium","devtools-protocol","e2e-testing","headless-browser","nodejs","playwright","test-automation","typescript","web-testing"],"created_at":"2026-04-13T00:20:48.735Z","updated_at":"2026-04-17T09:01:28.455Z","avatar_url":"https://github.com/toolstackhq.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cdpwright\n\n[![CI](https://github.com/toolstackhq/cdpwright/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/toolstackhq/cdpwright/actions/workflows/ci.yml)\n[![Tests](https://img.shields.io/badge/tests-vitest%20%2B%20integration-4caf50)](https://github.com/toolstackhq/cdpwright/actions/workflows/ci.yml)\n[![Chromium version check](https://github.com/toolstackhq/cdpwright/actions/workflows/chromium-revision.yml/badge.svg?branch=main)](https://github.com/toolstackhq/cdpwright/actions/workflows/chromium-revision.yml)\n[![npm version](https://img.shields.io/npm/v/@toolstackhq/cdpwright)](https://www.npmjs.com/package/@toolstackhq/cdpwright)\n[![license](https://img.shields.io/npm/l/@toolstackhq/cdpwright)](https://github.com/toolstackhq/cdpwright/blob/main/LICENSE)\n\nChromium-only automation built on the Chrome DevTools Protocol (CDP). A lightweight, Playwright-style API with `Browser`, `Context`, `Page`, `Frame`, and `Locator` primitives—no test runner included.\n\nPublished package size: about 708 KB unpacked on npm, so the library footprint stays small even though Chromium itself is installed separately.\n\n## Quick start\n\n```bash\nmkdir my-project \u0026\u0026 cd my-project\nnpm init -y\nnpm install @toolstackhq/cdpwright\nnpx cpw install     # downloads a pinned Chromium build once\n```\n\nCreate `quick.mjs` (the `.mjs` extension enables ES modules — no config needed):\n\n```js\n// quick.mjs\nimport { chromium, expect } from \"@toolstackhq/cdpwright\";\n\nconst browser = await chromium.launch({ headless: true });\nconst page = await browser.newPage();\n\nawait page.goto(\"https://example.com\");\nawait expect(page).element(\"h1\").toHaveText(/Example Domain/);\n\nawait browser.close();\n```\n\nRun it:\n```bash\nnode quick.mjs\n```\n\nIf you want Playwright-style lifecycle management outside a test runner, use `chromium.withBrowser()` and skip the manual close:\n\n```js\nimport { chromium } from \"@toolstackhq/cdpwright\";\n\nawait chromium.withBrowser({ headless: false, logEvents: true }, async (browser) =\u003e {\n  const page = await browser.newPage();\n  await page.goto(\"https://toolstackhq.github.io/bluledger/login\", { waitUntil: \"load\" });\n  await page.type(\"#customerId\", \"92718463\");\n  await page.typeSecure(\"#password\", \"Harbour!92\");\n  await page.click(\"#login-submit-button\");\n  await page.expect(\"#dashboard-transfer-money-link\").toBeVisible();\n});\n```\n\nIf you want to scaffold a test suite after `npm init -y`, run:\n\n```bash\nnpx cpw init test vitest\nnpx cpw init test mocha\nnpx cpw init test node\n```\n\nThat writes a sample test file and updates `package.json` with an `npm test` script for the chosen runner.\n\nVitest templates import the package's own assertion helper, so generated tests can use `cdpExpect(page).element(...)`. Mocha and `node:test` templates use built-in `assert`.\n\nAll scaffolded templates also include the Linux Chromium launch flags used by the repo's CI tests:\n\n```js\nargs: process.platform === \"linux\" ? [\"--no-sandbox\", \"--no-zygote\", \"--disable-dev-shm-usage\"] : []\n```\n\n\u003e **Tip:** If you prefer `.js` files, add `\"type\": \"module\"` to your `package.json`.\n\u003e For TypeScript, just rename to `quick.ts` and run with `tsx quick.ts` or `npx ts-node --esm quick.ts`.\n\n## Core ideas\n- CDP-only: no WebDriver, no playwright-core dependency.\n- Small surface: pages/frames/locators, plus built-in expect matchers.\n- Selector routing: CSS by default; XPath if the selector starts with `/`, `./`, `.//`, `..`, or `(/`. Shadow DOM via `\u003e\u003e\u003e` (e.g., `host \u003e\u003e\u003e button`).\n- Contexts: `browser.newContext()` gives incognito-style isolation without launching a new browser.\n- Helper: `chromium.withBrowser()` launches Chromium, runs your callback, and closes the browser automatically.\n- Scaffold: `cpw init test \u003crunner\u003e` writes a starter test file, a local HTML fixture, and an `npm test` script for Vitest, Mocha, or Node's built-in runner.\n- Scaffold templates are verified in CI for all supported runners.\n- Browser install: `npx cpw install` (or `--latest`) fetches Chromium into a local cache once, Playwright-style.\n\n## Key APIs\n- `chromium.launch(options)` → `Browser`\n- `browser.newContext()` → isolated `BrowserContext`\n- `browser.newPage()` / `context.newPage()` → `Page`\n- `page.goto(url, { waitUntil: \"load\" | \"domcontentloaded\" })`\n- Actions: `click`, `dblclick`, `type`, `typeSecure`, `fillInput`, `selectOption`, `setFileInput`\n- Queries: `query`, `queryAll`, `queryXPath`, `queryAllXPath`, `locator`\n- Assertions: `expect(page).element(\"selector\").toBeVisible()` (see `docs/guide/assertions.md`)\n\n## Architecture\n\n```mermaid\ngraph TD\n    subgraph CLI\n        CPW[\"cpw (CLI)\"]\n    end\n\n    subgraph Library API\n        USER[\"User code\"] --\u003e|chromium.launch| MGR[ChromiumManager]\n        MGR --\u003e|spawns| PROC[Chromium process]\n        PROC --\u003e|WebSocket| CDP[CDP Session]\n        CDP --\u003e BROWSER[Browser]\n        BROWSER --\u003e CTX[BrowserContext]\n        CTX --\u003e PAGE[Page]\n        PAGE --\u003e FRAME[Frame]\n        FRAME --\u003e LOC[Locator]\n        PAGE --\u003e EXPECT[\"expect()\"]\n    end\n\n    subgraph Download\n        CPW --\u003e|cpw install| DL[Downloader]\n        DL --\u003e|fetch + extract| CACHE[\"~/.cache/cdpwright\"]\n        MGR -.-\u003e|resolve executable| CACHE\n    end\n```\n\n## Docs\nFull guide and API reference: https://toolstackhq.github.io/cdpwright/ (built from `docs/` via VitePress). Start at `docs/guide/intro.md` or `docs/guide/api/`.\n\n## Demo app\n`index.html` is a local, data-driven visa-style wizard used to stress-test automation flows (no server required). Open it directly via `file://` to exercise navigation, conditionals, overlays, Shadow DOM, uploads, and receipts.\n\n## License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolstackhq%2Fcdpwright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoolstackhq%2Fcdpwright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolstackhq%2Fcdpwright/lists"}