{"id":13646341,"url":"https://github.com/lucgagan/auto-playwright","last_synced_at":"2025-04-12T12:37:29.015Z","repository":{"id":206661318,"uuid":"717161097","full_name":"lucgagan/auto-playwright","owner":"lucgagan","description":"Automating Playwright steps using ChatGPT.","archived":false,"fork":false,"pushed_at":"2025-01-21T01:49:30.000Z","size":146,"stargazers_count":691,"open_issues_count":25,"forks_count":99,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-05T10:01:52.234Z","etag":null,"topics":["ai","playwright"],"latest_commit_sha":null,"homepage":"https://ray.run/blog/auto-playwright","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucgagan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2023-11-10T17:42:39.000Z","updated_at":"2025-04-05T02:36:05.000Z","dependencies_parsed_at":"2025-02-28T09:13:35.147Z","dependency_job_id":"47b43630-05c2-4d48-bbb3-ff6965912cdc","html_url":"https://github.com/lucgagan/auto-playwright","commit_stats":null,"previous_names":["lucgagan/auto-playwright"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucgagan%2Fauto-playwright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucgagan%2Fauto-playwright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucgagan%2Fauto-playwright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucgagan%2Fauto-playwright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucgagan","download_url":"https://codeload.github.com/lucgagan/auto-playwright/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248567692,"owners_count":21125880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["ai","playwright"],"created_at":"2024-08-02T01:02:53.267Z","updated_at":"2025-04-12T12:37:28.995Z","avatar_url":"https://github.com/lucgagan.png","language":"TypeScript","readme":"# Auto Playwright\n\nRun Playwright tests using AI.\n\n## Setup\n\n1. Install `auto-playwright` dependency:\n\n```bash\nnpm install auto-playwright -D\n```\n\n2. This package relies on talking with OpenAI (https://openai.com/). You must export the API token as an enviroment variable or add it to your `.env` file:\n\n```bash\nexport OPENAI_API_KEY='sk-...\"\n```\n\n3. Import and use the `auto` function:\n\n```ts\nimport { test, expect } from \"@playwright/test\";\nimport { auto } from \"auto-playwright\";\n\ntest(\"auto Playwright example\", async ({ page }) =\u003e {\n  await page.goto(\"/\");\n\n  // `auto` can query data\n  // In this case, the result is plain-text contents of the header\n  const headerText = await auto(\"get the header text\", { page, test });\n\n  // `auto` can perform actions\n  // In this case, auto will find and fill in the search text input\n  await auto(`Type \"${headerText}\" in the search box`, { page, test });\n\n  // `auto` can assert the state of the website\n  // In this case, the result is a boolean outcome\n  const searchInputHasHeaderText = await auto(`Is the contents of the search box equal to \"${headerText}\"?`, { page, test });\n\n  expect(searchInputHasHeaderText).toBe(true);\n});\n```\n### Setup with Azure OpenAI\n\nInclude the StepOptions type with the values needed for connecting to Azure OpenAI.\n\n```ts\nimport { test, expect } from \"@playwright/test\";\nimport { auto } from \"auto-playwright\";\nimport { StepOptions } from \"../src/types\";\n\nconst apiKey = \"apikey\";\nconst resource = \"azure-resource-name\";\nconst model = \"model-deployment-name\";\n\nconst options: StepOptions = {\n   model: model,\n   openaiApiKey: apiKey,\n   openaiBaseUrl: `https://${resource}.openai.azure.com/openai/deployments/${model}`,\n   openaiDefaultQuery: { 'api-version': \"2023-07-01-preview\" },\n   openaiDefaultHeaders: { 'api-key': apiKey }\n};\n\ntest(\"auto Playwright example\", async ({ page }) =\u003e {\n  await page.goto(\"/\");\n\n  // `auto` can query data\n  // In this case, the result is plain-text contents of the header\n  const headerText = await auto(\"get the header text\", { page, test }, options);\n\n  // `auto` can perform actions\n  // In this case, auto will find and fill in the search text input\n  await auto(`Type \"${headerText}\" in the search box`, { page, test }, options);\n\n  // `auto` can assert the state of the website\n  // In this case, the result is a boolean outcome\n  const searchInputHasHeaderText = await auto(`Is the contents of the search box equal to \"${headerText}\"?`, { page, test }, options);\n\n  expect(searchInputHasHeaderText).toBe(true);\n});\n```\n\n## Usage\n\nAt minimum, the `auto` function requires a _plain text prompt_ and an _argument_ that contains your `page` and `test` (optional) objects.\n\n```ts\nauto(\"\u003cyour prompt\u003e\", { page, test });\n```\n\n### Browser automation\n\nRunning without the `test` parameter:\n\n```ts\nimport { chromium } from \"playwright\";\nimport { auto } from \"auto-playwright\";\n\n(async () =\u003e {\n  const browser = await chromium.launch({ headless: true });\n  const context = await browser.newContext();\n  const page = await context.newPage();\n  // Navigate to a website\n  await page.goto(\"https://www.example.com\");\n\n  // `auto` can query data\n  // In this case, the result is plain-text contents of the header\n  const res = await auto(\"get the header text\", { page });\n\n  // use res.query to get a query result.\n  console.log(res);\n  await page.close();\n})();\n```\n\n### Debug\n\nYou may pass a `debug` attribute as the third parameter to the `auto` function. This will print the prompt and the commands executed by OpenAI.\n\n```ts\nawait auto(\"get the header text\", { page, test }, { debug: true });\n```\n\nYou may also set environment variable `AUTO_PLAYWRIGHT_DEBUG=true`, which will enable debugging for all `auto` calls.\n\n```bash\nexport AUTO_PLAYWRIGHT_DEBUG=true\n```\n\n## Supported Browsers\n\nEvery browser that Playwright supports.\n\n## Additional Options\n\nThere are additional options you can pass as a third argument:\n\n```ts\nconst options = {\n  // If true, debugging information is printed in the console.\n  debug: boolean,\n  // The OpenAI model (https://platform.openai.com/docs/models/overview)\n  model: \"gpt-4-1106-preview\",\n  // The OpenAI API key\n  openaiApiKey: 'sk-...',\n};\n\nauto(\"\u003cyour prompt\u003e\", { page, test }, options);\n```\n\n## Supported Actions \u0026 Return Values\n\nDepending on the `type` of action (inferred by the `auto` function), there are different behaviors and return types.\n\n### Action\n\nAn action (e.g. \"click\") is some simulated user interaction with the page, e.g. a click on a link. Actions will return `undefined`` if they were successful and will throw an error if they failed, e.g.\n\n```ts\ntry {\n  await auto(\"click the link\", { page, test });\n} catch (e) {\n  console.error(\"failed to click the link\");\n}\n```\n\n### Query\n\nA query will return requested data from the page as a string, e.g.\n\n```ts\nconst linkText = await auto(\"Get the text of the first link\", { page, test });\n\nconsole.log(\"The link text is\", linkText);\n```\n\n### Assert\n\nAn assertion is a question that will return `true` or `false`, e.g.\n\n```ts\nconst thereAreThreeLinks = await auto(\"Are there 3 links on the page?\", {\n  page,\n  test,\n});\n\nconsole.log(`\"There are 3 links\" is a ${thereAreThreeLinks} statement`);\n```\n\n## Why use Auto Playwright?\n\n| Aspect                         | Conventional Approach                                                               | Testing with Auto Playwright                                                                                                 |\n| ------------------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| **Coupling with Markup**       | Strongly linked to the application's markup.                                        | Eliminates the use of selectors; actions are determined by the AI assistant at runtime.                                      |\n| **Speed of Implementation**    | Slower implementation due to the need for precise code translation for each action. | Rapid test creation using simple, plain text instructions for actions and assertions.                                        |\n| **Handling Complex Scenarios** | Automating complex scenarios is challenging and prone to frequent failures.         | Facilitates testing of complex scenarios by focusing on the intended test outcomes.                                          |\n| **Test Writing Timing**        | Can only write tests after the complete development of the functionality.           | Enables a Test-Driven Development (TDD) approach, allowing test writing concurrent with or before functionality development. |\n\n## Supported Playwright Actions\n\n- `locator.blur`\n- `locator.boundingBox`\n- `locator.check`\n- `locator.clear`\n- `locator.click`\n- `locator.count`\n- `locator.fill`\n- `locator.getAttribute`\n- `locator.innerHTML`\n- `locator.innerText`\n- `locator.inputValue`\n- `locator.isChecked`\n- `locator.isEditable`\n- `locator.isEnabled`\n- `locator.isVisible`\n- `locator.textContent`\n- `locator.uncheck`\n- `page.goto`\n- `page.keyboard.press`\n\nAdding new actions is easy: just update the `functions` in [`src/completeTask.ts`](src/completeTask.ts).\n\n## Pricing\n\nThis library is free. However, there are costs associated with using OpenAI. You can find more information about pricing here: https://openai.com/pricing/.\n\n\u003cdetails\u003e\n  \u003csummary\u003eExample\u003c/summary\u003e\n\nUsing https://ray.run/ as an example, the cost of running a test step is approximately $0.01 using GPT-4 Turbo (and $0.001 using GPT-3.5 Turbo).\n\nThe low cost is in part because `auto-playwright` uses HTML sanitization to reduce the payload size, e.g. What follows is the payload that would be submitted for https://ray.run/.\n\nNaturally, the price will vary dramatically depending on the payload.\n\n```html\n\u003cdiv class=\"cYdhWw dKnOgO geGbZz bGoBgk jkEels\"\u003e\n  \u003cdiv class=\"kSmiQp fPSBzf bnYmbW dXscgu xJzwH jTWvec gzBMzy\"\u003e\n    \u003ch1 class=\"fwYeZS fwlORb pdjVK bccLBY fsAQjR fyszFl WNJim fzozfU\"\u003e\n      Learn Playwright\n    \u003c/h1\u003e\n    \u003ch2 class=\"cakMWc ptfck bBmAxp hSiiri xJzwS gnfYng jTWvec fzozfU\"\u003e\n      Resources for learning end-to-end testing using Playwright automation\n      framework\n    \u003c/h2\u003e\n    \u003cdiv\n      class=\"bLTbYS gvHvKe cHEBuD ddgODW jsxhGC kdTEUJ ilCTXp iQHbtH yuxBn ilIXfy gPeiPq ivcdqp isDTsq jyZWmS ivdkBK cERSkX hdAwi ezvbLT jNrAaV jsxhGJ fzozCb\"\n    \u003e\u003c/div\u003e\n  \u003c/div\u003e\n  \u003cdiv class=\"cYdhWw dpjphg cqUdSC fasMpP\"\u003e\n    \u003ca\n      class=\"gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group\"\n      href=\"/blog\"\n      \u003e\u003cdiv class=\"plfYl bccLBY hSiiri fNBpvX\"\u003eBlog\u003c/div\u003e\n      \u003cdiv class=\"jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu\"\u003e\n        \u003cp\u003eLearn in depth subjects about end-to-end testing.\u003c/p\u003e\n      \u003c/div\u003e\u003c/a\n    \u003e\u003ca\n      class=\"gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group\"\n      href=\"/ask\"\n      \u003e\u003cdiv class=\"plfYl bccLBY hSiiri fNBpvX\"\u003eAsk AI\u003c/div\u003e\n      \u003cdiv class=\"jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu\"\u003e\n        \u003cp\u003eAsk ChatGPT Playwright questions.\u003c/p\u003e\n      \u003c/div\u003e\u003c/a\n    \u003e\u003ca\n      class=\"gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group\"\n      href=\"/tools\"\n      \u003e\u003cdiv class=\"plfYl bccLBY hSiiri fNBpvX\"\u003eDev Tools\u003c/div\u003e\n      \u003cdiv class=\"jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu\"\u003e\n        \u003cp\u003eAll-in-one toolbox for QA engineers.\u003c/p\u003e\n      \u003c/div\u003e\u003c/a\n    \u003e\u003ca\n      class=\"gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group\"\n      href=\"/jobs\"\n      \u003e\u003cdiv class=\"plfYl bccLBY hSiiri fNBpvX\"\u003eQA Jobs\u003c/div\u003e\n      \u003cdiv class=\"jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu\"\u003e\n        \u003cp\u003eHandpicked QA and Automation opportunities.\u003c/p\u003e\n      \u003c/div\u003e\u003c/a\n    \u003e\u003ca\n      class=\"gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group\"\n      href=\"/questions\"\n      \u003e\u003cdiv class=\"plfYl bccLBY hSiiri fNBpvX\"\u003eQuestions\u003c/div\u003e\n      \u003cdiv class=\"jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu\"\u003e\n        \u003cp\u003eAsk AI answered questions about Playwright.\u003c/p\u003e\n      \u003c/div\u003e\u003c/a\n    \u003e\u003ca\n      class=\"gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group\"\n      href=\"/discord-forum\"\n      \u003e\u003cdiv class=\"plfYl bccLBY hSiiri fNBpvX\"\u003eDiscord Forum\u003c/div\u003e\n      \u003cdiv class=\"jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu\"\u003e\n        \u003cp\u003eArchive of Discord Forum posts about Playwright.\u003c/p\u003e\n      \u003c/div\u003e\u003c/a\n    \u003e\u003ca\n      class=\"gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group\"\n      href=\"/videos\"\n      \u003e\u003cdiv class=\"plfYl bccLBY hSiiri fNBpvX\"\u003eVideos\u003c/div\u003e\n      \u003cdiv class=\"jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu\"\u003e\n        \u003cp\u003eTutorials, conference talks, and release videos.\u003c/p\u003e\n      \u003c/div\u003e\u003c/a\n    \u003e\u003ca\n      class=\"gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group\"\n      href=\"/browser-extension\"\n      \u003e\u003cdiv class=\"plfYl bccLBY hSiiri fNBpvX\"\u003eBrowser Extension\u003c/div\u003e\n      \u003cdiv class=\"jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu\"\u003e\n        \u003cp\u003eGUI for generating Playwright locators.\u003c/p\u003e\n      \u003c/div\u003e\u003c/a\n    \u003e\u003ca\n      class=\"gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group\"\n      href=\"/wiki\"\n      \u003e\u003cdiv class=\"plfYl bccLBY hSiiri fNBpvX\"\u003eQA Wiki\u003c/div\u003e\n      \u003cdiv class=\"jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu\"\u003e\n        \u003cp\u003eDefinitions of common end-to-end testing terms.\u003c/p\u003e\n      \u003c/div\u003e\u003c/a\n    \u003e\n  \u003c/div\u003e\n  \u003cdiv\n    class=\"kSmiQp fPSBzf pKTba eTDpsp legDhJ hSiiri hdaZLM jTWvec gzBMzy bGySga fzoybr\"\n  \u003e\n    \u003cp class=\"dXhlDK leOtqz glpWRZ fNCcFz\"\u003e\n      Use \u003ckbd class=\"bWhrAL XAzZz cakMWc bUyOMB bmOrOm fyszFl dTmriP\"\u003e⌘\u003c/kbd\u003e +\n      \u003ckbd\u003ek\u003c/kbd\u003e + \"Tools\" to quickly access all tools.\n    \u003c/p\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n\u003c/details\u003e\n\n## Implementation\n\n### HTML Sanitization\n\nThe `auto` function uses [sanitize-html](https://www.npmjs.com/package/sanitize-html) to sanitize the HTML of the page before sending it to OpenAI. This is done to reduce cost and improve the quality of the generated text.\n\n## ZeroStep\n\nThis project draws its inspiration from [ZeroStep](https://zerostep.com/). ZeroStep offers a similar API but with a more robust implementation through its proprietary backend. Auto Playwright was created with the aim of exploring the underlying technology of ZeroStep and establishing a basis for an open-source version of their software. For production environments, I suggest opting for ZeroStep.\n\nHere's a side-by-side comparison of Auto Playwright and ZeroStep:\n\n|Criteria|Auto Playwright|ZeroStep|\n|---|---|---|\n|Uses OpenAI API|Yes|No[^3]|\n|Uses plain-text prompts|Yes|No|\n|Uses [`functions`](https://www.npmjs.com/package/openai#automated-function-calls) SDK|Yes|No|\n|Uses HTML sanitization|Yes|No|\n|Uses Playwright API|Yes|No[^4]|\n|Uses screenshots|No|Yes|\n|Uses queue|No|Yes|\n|Uses WebSockets|No|Yes|\n|Snapshots|HTML|DOM|\n|Implements parallelism|No|Yes|\n|Allows scrolling|No|Yes|\n|Provides fixtures|No|Yes|\n|License|MIT|MIT|\n\n[^3]: Uses ZeroStep proprietary API.\n[^4]: Uses _some_ Playwright API, but predominantly relies on Chrome DevTools Protocol (CDP).\n\n\u003cdetails\u003e\n  \u003csummary\u003eZero Step License\u003c/summary\u003e\n\n```\nMIT License\n\nCopyright (c) 2023 Reflect Software Inc\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n```\n\u003c/details\u003e\n","funding_links":[],"categories":["Others","🤖 AI \u0026 Machine Learning","TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucgagan%2Fauto-playwright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucgagan%2Fauto-playwright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucgagan%2Fauto-playwright/lists"}