Quick Start

Fully-featured docs are coming in the next few weeks. For the time being, here’s a quick-start that’ll get you up-and-running fast…

---

This project will guide you through setting up a typescript project for both browser automation and testing. We assume you have node.js installed on your machine.

Initialize your project

First off, let’s install the necessary packages. Create a new directory, and inside it, run:

npm init -y
npm install playwright @playwright/test typescript tsx

Next, let’s set up TypeScript by generating a tsconfig.json file.

npx tsc --init --strict

In your package.json, add the following scripts to easily run your TypeScript code:

"scripts": {
  "start": "tsx script.ts",
  "watch": "tsx --watch script.ts",
  "test": "playwright test"
}

Lastly, install let’s install the headless browsers themselves:

npx playwright install

Write a Playwright automation

Create a script.ts file in your project directory and add the following:

import {chromium} from "playwright";

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto("https://www.browsercat.com");
  await browser.close();
})();

Then run:

npm run start

This opens a Chromium browser, navigates to https://www.browsercat.com, and then closes the browser. Easy-peasy!

Use the following command to re-run the script every time you make a change. This is very useful for experimenting.

npm run watch

Now let’s explore some automation strategies…

Scrape content

Let’s scrape the content of an H1 element.

const content = await page.$eval("h1", (el) => el.textContent);
console.log(`H1 content: ${content}`);

Submit a contact form

You can use a similar strategy to authenticate before scraping data.

await page.fill('input[name="name"]', "John Doe");
await page.fill('input[name="email"]', "john@example.com");
await page.click("button#submit");

Take a screenshot

You can use this technique to generate certificates, social media cards for blog posts, or during testing to ensure your page designs didn’t break.

await page.screenshot({path: "screenshot.png"});

Generate a PDF

This is very useful when you need to generate invoices or custom marketing materials.

await page.pdf({path: "mypdf.pdf"});

Record a video

This strategy is invaluable for keeping your help videos in sync with changes to your web app.

await page.video({path: "video.mp4"});

Send your script to production

Once your script is ready, it’s time to productionalize it! Consider using a cronjob service to run your script on an interval, or deploy it to an API endpoint so that you can trigger the script on demand.

Of course, you don’t want to deploy a 2-gig browser to your host. It’s costly, slow, and a pain to maintain. Instead, sign up for a BrowserCat account, then replace chromium.launch() with chromium.connect()…

const browser = await chromium.connect({
  wsEndpoint: "wss://api.browsercat.com/connect",
  headers: {"Api-Key": "[YOUR API KEY]"},
});

That’s it! Now you can trigger the script on demand, completely in parallel. This can shave minutes off your deployment pipeline and hundreds of dollars in hosting costs. Meanwhile, we offer a free plan and charge literally pennies!

Write E2E tests

Now lets change direction and write some end-to-end tests. This will ensure that our app actually works the way we want it to before it hits production.

First, create a playwright.config.ts configuration file:

import {PlaywrightTestConfig} from "@playwright/test";

const config: PlaywrightTestConfig = {};

export default config;

Now, write a test script that searches for an H1 element. Create a file example.spec.ts:

import {test} from "@playwright/test";

test("Check H1 element", async ({page}) => {
  await page.goto("https://www.browsercat.com");
  const h1Element = await page.$("h1");
  expect(h1Element).not.toBeNull();
});

Run the test:

npm run test

Send your tests to production

With BrowserCat, deploying your tests is just as easy as deploying your scripts. Simply update your playwright.config.ts as follows:

const config: PlaywrightTestConfig = {
  use: {
    browserName: "chromium",
    connectOptions: {
      wsEndpoint: "wss://api.browsercat.com/connect",
      headers: {"Api-Key": "[YOUR API KEY]"},
    },
  },
};

That’s it! You now have a working setup for Playwright and TypeScript, along with some essential features for web automation and testing.

Stay tuned for updated docs. We’re working on them right now!