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

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

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.