{"id":13651421,"url":"https://github.com/zerostep-ai/zerostep","last_synced_at":"2025-04-22T22:31:07.979Z","repository":{"id":204969346,"uuid":"713088130","full_name":"zerostep-ai/zerostep","owner":"zerostep-ai","description":"Supercharge your Playwright tests with AI","archived":false,"fork":false,"pushed_at":"2023-12-13T16:21:11.000Z","size":114,"stargazers_count":124,"open_issues_count":2,"forks_count":5,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-04-16T03:29:37.847Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/zerostep-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-11-01T20:14:23.000Z","updated_at":"2024-04-11T21:26:27.000Z","dependencies_parsed_at":"2023-11-07T00:15:26.484Z","dependency_job_id":"3c0cd1c4-ccf4-401e-821f-f97a04e0e3e3","html_url":"https://github.com/zerostep-ai/zerostep","commit_stats":null,"previous_names":["zerostep-ai/zerostep"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerostep-ai%2Fzerostep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerostep-ai%2Fzerostep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerostep-ai%2Fzerostep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerostep-ai%2Fzerostep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zerostep-ai","download_url":"https://codeload.github.com/zerostep-ai/zerostep/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250333920,"owners_count":21413477,"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":[],"created_at":"2024-08-02T02:00:49.294Z","updated_at":"2025-04-22T22:31:07.685Z","avatar_url":"https://github.com/zerostep-ai.png","language":"TypeScript","funding_links":[],"categories":["AI Agents for Testing","Utils"],"sub_categories":[".NET"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource\n      srcset=\"https://github.com/zerostep-ai/zerostep/assets/1895887/4bb7ea13-100d-4fdd-84a6-657751bd2197\"\n      media=\"(prefers-color-scheme: dark)\"\n      height=\"200\" width=\"200\"\n    /\u003e\n    \u003cimg\n      src=\"https://github.com/zerostep-ai/zerostep/assets/1895887/7de0b6bd-eed9-4977-b25e-495ecaf197c7\"\n      alt=\"ZeroStep Logo\"\n      height=\"200\" width=\"200\"\n    /\u003e\n  \u003c/picture\u003e\n\u003c/div\u003e\n\n# Zerostep\n\nSupercharge your Playwright tests with AI. Learn more at https://zerostep.com\n\n## Setup\n\n1. Install the @zerostep/playwright dependency\n   ```sh\n   $ npm i @zerostep/playwright -D\n   ```\n\n2. This package relies on an environment variable with your zerostep token being exposed to\n   the playwright process, or a config file that holds the token. This token can be found\n   in your account on https://app.zerostep.com. You can expose the environment variable\n   however you'd like, e.g.\n   ```sh\n   $ export ZEROSTEP_TOKEN=\"\u003cyour token here\u003e\"\n   ```\n   Alternatively, you can create a `zerostep.config.json` file in the root of your project\n   and store the token there, e.g.\n   ```json\n   {\n     \"TOKEN\": \"\u003cyour token here\u003e\"\n   }\n   ```\n\n3. Import and use the `ai` function\n   ```ts\n   import { test } from '@playwright/test'\n   import { ai } from '@zerostep/playwright'\n\n   test('zerostep example', async ({ page }) =\u003e {\n     await page.goto('https://zerostep.com/')\n\n     // An object with page and test must be passed into every call\n     const aiArgs = { page, test }\n     const headerText = await ai('Get the header text', aiArgs)\n     await page.goto('https://google.com/')\n     await ai(`Type \"${headerText}\" in the search box`, aiArgs)\n     await ai('Press enter', aiArgs)\n   })\n   ```\n\n## Usage\n\nAt minimum, the `ai()` function requires a plain text prompt and an argument that contains your\n`page` and `test` objects.\n\n```ts\nai('\u003cyour prompt\u003e', { page, test })\n```\n\nYou can also pass multiple prompts in an array as the first argument. In that\ncase prompts will be run concurrently in chunks. The number of prompts being run\nin a chunk defaults to `10` and can be controlled by `options`, see below. Note\nthat each prompt passed into the array counts as a single `ai()` call.\n\n```ts\nai(['\u003cprompt 1\u003e', '\u003cprompt 2\u003e', '\u003cprompt 3\u003e'])\n```\n\n### Playwright Fixture\n\nThe `zerostep/playwright` library ships with a playwright fixture out of the box. This allows\nyou to call `ai()` steps without passing the `{ test, page }` argument every time. You can\nuse the [playwright docs](https://playwright.dev/docs/test-fixtures#creating-a-fixture) as a guide\nto get setup, but here's some example code\n\n```ts\n// my-test.ts\nimport { test as base } from '@playwright/test'\nimport { aiFixture, type AiFixture } from '@zerostep/playwright'\n\nexport const test = base.extend\u003cAiFixture\u003e({\n  ...aiFixture(base),\n})\n```\n\n```ts\n// my-spec.ts\nimport { test } from './my-test.ts'\n\ntest('I can foo', async ({ ai }) =\u003e {\n  await ai('click bar')\n})\n```\n\nThere is example code in the `/examples/playwright-demo/tests/zerostep-regression.spec.ts` file\n\n\n### Supported Browsers\n\nThis package only supports executing `ai()` steps in Chromium browsers.\n\n### Additional Options\n\nThere are additional options you can pass as a third argument\n\n```ts\nconst options = {\n  debug?: boolean,                      // If true, debugging information is returned from the ai() call.\n  type?: 'action' | 'assert' | 'query', // Forces the ai step to be interpreted as the specified type.\n  model?: 'GPT_3.5',                    // The ai model to use, only GPT_3.5 is supported\n  disableScroll?: boolean,              // If true, the ai will not scroll out of view elements into view.\n  parallelism?: number,                 // The number of prompts that will be run in a chunk, applies when passing an array of prompts to ai(). Defaults to 10.\n  failImmediately?: boolean             // If true and an array of prompts was provided, the function will throw immediately if any prompt throws. Defaults to false.\n}\n\nai('\u003cyour prompt\u003e', { page, test }, options)\n```\n\n### Supported Actions \u0026 Return Values\n\nDepending on the `type` of action (specified above or inferred by the ai function), there\nare different behaviors and return types.\n\n**Action**: An action (e.g. \"click\") is some simulated user interaction with the page, e.g.\na click on a link. It will scroll to perform the given task if required, but favors elements\nwithin the current viewport. Actions will return undefined if they were successful and will\nthrow an error if they failed, e.g.\n\n```ts\ntry {\n  await ai('Click the link', { page, test })\n} catch (e) {\n  console.error('Failed to click the link')\n}\n```\n\nAction prompts will resolve to one or more of the following browser actions:\n- Click\n- Hover\n- Text Input\n- 'Enter' keypress\n- Scroll\n- Navigating to a new URL\n\nOther browser actions such as drag-and-drops and file uploads are not currently supported.\n\n**Query**: A query will return requested data from the visible portion of the page as a string, e.g.\n\n```ts\nconst linkText = await ai('Get the text of the first link', { page, test })\nconsole.log('The link text is', linkText)\n```\n\n**Assert**: An assertion is a question that will return true or false based on the visible portion of the page, e.g.\n```ts\nconst thereAreThreeLinks = await ai('Are there 3 links on the page?', { page, test })\nconsole.log(`\"There are 3 links\" is a ${thereAreThreeLinks} statement`)\n```\n\n## Examples\n\nThis repository comes with a demo to quickly experiment with the ai() function. In order to\nstart using it you need to\n\n1. Build the local version of the zerostep/playwright package\n```sh\ncd packages/playwright\nnpm install\nnpm run build\n```\n2. Install the zerostep/playwright dependency in the examples directory\n```sh\ncd ../../examples/playwright-demo\nnpm install\n```\n3. Expose the `ZEROSTEP_TOKEN` environment variable or config value (see the \"Setup\" section above)\n4. Run the tests, with or without UI mode\n```sh\n$ npm run test # or npm run test-ui\n```\n\n## Best Practices\n\nZeroStep AI prompts need not conform to any predefined syntax. However, we recommend following these best practices to\nensure your prompts work as you intend:\n\n- Write your prompts in complete English sentences with no spelling or grammatical mistakes.\n- Put quotes around any text that should appear exactly as described. e.g. `Click on the \"Login\" button`\n- Don't include CSS/XPath selectors in your prompt, or any other implementation-level details.\n- Don't combine two or more instructions in the same prompt. e.g.\n  `Click on the Settings icon and then click on the \"User Profile\" link`. Instead, each prompt should contain one\n  distinct action, query, or assertion.\n   - Note: The exception here is Action prompts that perform a single logical task which is accomplished by multiple\n     actions. In other words, a prompt like `Fill out the form with realistic values` is a perfectly fine prompt.\n- Write prompts to the level of specificity dictated by your requirements. Some level of ambiguity is fine and even\n  desirable in a lot of circumstances. A prompt such as `Click on the \"Get Started\" link` will work even when there are\n  multiple \"Get Started\" links on the page, or if the page is completely redesigned.\n\n## Community\n\nHave questions or suggestions? [Join our Discord](https://discord.gg/BcDmfWqSGe)!\n\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource\n      srcset=\"https://github.com/zerostep-ai/zerostep/assets/1895887/74ad3b31-ac30-4376-be58-236cf1f7c033\"\n      media=\"(prefers-color-scheme: dark)\"\n      height=\"60\" width=\"60\"\n    /\u003e\n    \u003cimg\n      src=\"https://github.com/zerostep-ai/zerostep/assets/1895887/9a9a848a-302c-4a6e-8f4a-dd7e7633757d\"\n      alt=\"ZeroStep Logo\"\n      height=\"60\" width=\"60\"\n    /\u003e\n  \u003c/picture\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerostep-ai%2Fzerostep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzerostep-ai%2Fzerostep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerostep-ai%2Fzerostep/lists"}