Play-ai NPM | npm.io

Play AI

Run Playwright tests efficiently using AI.

Installation

Install the play-ai package as a development dependency:

npm install -D play-ai

Set up OpenAI API key:

export OPENAI_API_KEY='sk-...'

Set up maximum task prompt character count (by default set to 2000):

export MAX_TASK_CHARS='2000'

Import and use the play function in your test scripts:

import { expect, test, Page } from "@playwright/test";
import { play } from "play-ai";
import * as dotenv from "dotenv";

dotenv.config();
const options = undefined;

test.describe("Playwright AI Integration", () => {
    test.beforeEach(async ({ page }) => {
        await page.goto("https://www.saucedemo.com/");
    });

    test.afterEach(async ({ page }) => {
        await page.close();
    });

    test("AI-Powered Playwright Test", async ({ page }) => {
        await play("Type 'standard_user' in the Username field", { page, test }, options);
        await play("Type 'secret_sauce' in the Password field", { page, test }, options);
        await play("Click the Login button", { page, test }, options);

        const headerText = await play("Retrieve the header logo text", { page, test }, options);
        expect(headerText).toBe("Swag Labs");
    });
});

You can also chain multiple prompts in the play function within your test scripts:

import { expect, test, Page } from "@playwright/test";
import { play } from "play-ai";
import * as dotenv from "dotenv";

const options = undefined;
dotenv.config();

test.describe("Playwright Integration With AI Suite", () => {
    test.beforeEach(async ({ page }) => {
        await page.goto("https://www.saucedemo.com/");
    });

    test.afterEach(async ({ page }) => {
        await page.close();
    });

    test("PW With AI Test With Nested Task", async ({ page }) => {
        await play(
            [
                `Type "standard_user" in the Username field`,
                `Type "secret_sauce" in the Password field`,
                `Click the Login button`,
            ],
            { page, test },
            options,
        );

        const headerLabelText = await play("get the header logo label text", { page, test }, options);

        expect(headerLabelText).toBe("Swag Labs");

        const firstLinkText = await play(
            "get the first inventory item name from inventory list",
            { page, test },
            options,
        );
        expect(firstLinkText).toBe("Sauce Labs Backpack");
    });
});

Usage

Execute Playwright actions using plain text commands:

play("<your prompt>", { page, test });

Debugging

Enable debugging with:

await play("Retrieve the header text", { page, test }, { debug: true });

or set:

export PLAY_AI_DEBUG=true

Supported Browsers

Play AI supports all Playwright-compatible browsers.

Configuration Options

const options = {
    debug: true,
    model: "gpt-4O",
    openaiApiKey: "sk-...",
};

Why Play AI?

Feature	Traditional Testing	AI-Powered Testing
Selector Dependency	High	Low
Implementation Speed	Slow	Fast
Handling Complex Scenarios	Difficult	Easier

Supported Actions

page.goto
locator.click
locator.fill
locator.textContent
locator.blur
locator.boundingBox
locator.check
locator.clear
locator.count
locator.getAttribute
locator.innerHTML
locator.innerText
locator.inputValue
locator.isChecked
locator.isEditable
locator.isEnabled
locator.isVisible
locator.uncheck
locator.dblclick
locator.scrollIntoView
locator.scrollIntoViewIfNeeded
locator.hover
locator.waitForPageLoad
locator.expectToBe
locator.expectNotToBe

Pricing

Play AI is free, but OpenAI API calls may incur costs. See OpenAI’s pricing.

Related Projects

Criteria	Play-AI	Auto Playwright	ZeroStep
Uses OpenAI API	✅ Yes	✅ Yes	❌ No^3
Uses plain-text prompts	✅ Yes	✅ Yes	❌ No
Uses `functions` SDK	✅ Yes	✅ Yes	❌ No
Uses HTML sanitization	✅ Yes	✅ Yes	❌ No
Uses Playwright API	✅ Yes	✅ Yes	❌ No^4
Uses screenshots	❌ No	❌ No	✅ Yes
Uses queue	❌ No	❌ No	✅ Yes
Uses WebSockets	❌ No	❌ No	✅ Yes
Snapshots	HTML	HTML	DOM
Implements parallelism	✅ Yes	❌ No	✅ Yes
Allows scrolling	✅ Yes	❌ No	✅ Yes
Provides fixtures	✅ Yes	❌ No	✅ Yes
License	MIT	MIT	MIT

Collaborator Instructions

We welcome contributions from the community! Here are some guidelines to help you get started:

Getting Started

Fork the Repository: Click the "Fork" button at the top right of this repository to create a copy of the repository in your GitHub account.
Clone the Repository: Clone the forked repository to your local machine using the following command:
```
git clone https://github.com/<your-username>/play-ai.git
```
Install Dependencies: Navigate to the project directory and install the required dependencies:
```
cd play-ai
npm install
```
Set Up Environment Variables: Create a .env file in the root directory and add your OpenAI API key:
```
echo "OPENAI_API_KEY='sk-...'" > .env
```

Running Tests

Before making any changes, ensure that the existing tests pass. You can run the tests using the following command:

npm test

Making Changes

Create a New Branch: Create a new branch for your feature or bug fix:

git checkout -b feature/your-feature-name

Make Your Changes: Implement your feature or bug fix.
Run Tests: Ensure that all tests pass after your changes:

npm test

Commit Your Changes: Commit your changes with a descriptive commit message:

git add .
git commit -m "Add feature: your feature description"

Push to Your Fork: Push your changes to your forked repository:

git push origin feature/your-feature-name

Create a Pull Request: Go to the original repository and create a pull request from your forked repository. Provide a clear description of your changes and any relevant information.

Code Style

Please follow the existing code style and conventions. We use Prettier(Sure! Here is a section for collaborator instructions that you can add to your README.md file:

## Collaborator Instructions

We welcome contributions from the community! Here are some guidelines to help you get started:

### Getting Started

1. **Fork the Repository**: Click the "Fork" button at the top right of this repository to create a copy of the repository in your GitHub account.

2. **Clone the Repository**: Clone the forked repository to your local machine using the following command:
    ```bash
    git clone https://github.com/<your-username>/play-ai.git
    ```

Install Dependencies: Navigate to the project directory and install the required dependencies:
```
cd play-ai
npm install
```
Set Up Environment Variables: Create a .env file in the root directory and add your OpenAI API key:
```
echo "OPENAI_API_KEY='sk-...'" > .env
```

Running Tests

Before making any changes, ensure that the existing tests pass. You can run the tests using the following command:

npm test

Making Changes

Create a New Branch: Create a new branch for your feature or bug fix:
```
git checkout -b feature/your-feature-name
```
Make Your Changes: Implement your feature or bug fix.
Run Tests: Ensure that all tests pass after your changes:
```
npm test
```
Commit Your Changes: Commit your changes with a descriptive commit message:
```
git add .
git commit -m "Add feature: your feature description"
```
Push to Your Fork: Push your changes to your forked repository:
```
git push origin feature/your-feature-name
```
Create a Pull Request: Go to the original repository and create a pull request from your forked repository. Provide a clear description of your changes and any relevant information.

Code Style

Please follow the existing code style and conventions. We use Prettier for code formatting. You can format your code using the following command:

npm run format

Reporting Issues

If you find any bugs or have feature requests, please open an issue on GitHub. Provide as much detail as possible to help us understand and address the issue.

Contact

If you have any questions or need further assistance, feel free to reach out to the project maintainers.

Thank you for contributing to Play AI! 🚀

This section provides clear instructions for collaborators on how to get started, make changes, run tests, and create pull requests. It also includes guidelines for code style and reporting issues.
This section provides clear instructions for collaborators on how to get started, make changes, run tests, and create pull requests. It also includes guidelines for code style and reporting issues.) for code formatting. You can format your code using the following command:

```bash
npm run format

Reporting Issues

If you find any bugs or have feature requests, please open an issue on GitHub. Provide as much detail as possible to help us understand and address the issue.

Contact

If you have any questions or need further assistance, feel free to reach out to the project maintainers.

Thank you for contributing to Play AI! 🚀

Play AI simplifies Playwright automation using natural language commands, making test creation faster and more intuitive. 🚀

MIT License

Copyright (c) 2025 Muralidharan Rajendran (muralidharan92)

Permission 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:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE 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.

openai playwright automation testing AI end-to-end testing play-ai playai PlayAI

@types/sanitize-html openai sanitize-html zod

4 months ago

4 months ago

4 months ago

5 months ago

5 months ago