npm package: @plutoxyz/automation-utils
Description: A utility library for Playwright designed to make your Pluto automation scripts more resilient and easier to write.
Author: Pluto
Latest version: 0.0.1

# @plutoxyz/automation-utils

A utility library for Playwright designed to make your Pluto automation scripts more resilient and easier to write.

The core of this library is a `PlutoPage` object, a wrapper around Playwright's `Page`. It's designed to prevent common "stale element" errors by dynamically targeting the currently active page in a browser context, rather than being tied to a specific page instance. This is especially useful for modern, complex web applications.

## Installation

You can install the package using your favorite package manager:

```bash
npm install @plutoxyz/automation-utils
```

## Getting Started

When writing a Pluto script, you get a browser context from the `@plutoxyz/automation` library. Instead of using a standard Playwright `Page`, you should immediately use the `createPlutoPage` function from this library to create a resilient page object that will make your script more robust.

### Example

```typescript
import { createSession } from "@plutoxyz/automation";
import { chromium } from "playwright-core";
import { createPlutoPage, PlutoPage } from "@plutoxyz/automation-utils";

// 1. Get the Pluto automation session
const session = await createSession();

// 2. Connect to the browser instance provided by the session
const browser = await chromium.connectOverCDP(await session.cdp());
const context = browser.contexts()[0];

// 3. Create a PlutoPage instead of a regular Playwright page
const page: PlutoPage = createPlutoPage(context);

// 4. Now, use 'page' for the rest of your script.
// It will always target the active page, making your script robust.
const locator = await page.loadAndGet(
  "https://some-website.com",
  page.getByText("Example Domain")
);

if (await page.exists(locator)) {
  console.log(`Found locator: ${await locator.textContent()}`);
} else {
  console.log("Locator not found");
}

// ... your automation logic here

await browser.close();
await session.close();
```

### Additional Utilities

`PlutoPage` also comes with a few extra helper methods to simplify common automation tasks:

- `exists(locator, timeout?, interval?)`: Checks for the presence of an element without throwing an error if it's not found immediately. Returns `true` if the element exists, `false` otherwise.
- `waitFor(locator, timeout?)`: A more lenient `waitFor` that returns the `Locator` if found, or `null` if it times out, preventing script crashes.
- `waitForAnyNav(timeout?)`: Waits for any type of navigation event to complete (`load`, `domcontentloaded`, or `networkidle`).
- `loadAndGet(url, locator, waitUntil?, timeout?)`: A convenient method that navigates to a URL and waits for a specific locator to be present, returning the locator or `null`. Useful for detecting page load by waiting for a specific element to be present.

## Development

To contribute, you can build the library and run a watcher for development.

- `npm run build`: Compiles the TypeScript source code into JavaScript in the `dist` directory.
- `npm run dev`: Starts a watcher that automatically recompiles the code whenever a file is changed.