puppet-strings

A better interface for common browser automation workflows

Example

import {
  openBrowser, closeBrowser, openTab, waitForNavigation,
  findElement, fillInElement, clickElement, evalInTab
} from 'puppet-strings'

async function run() {
  const browser = await openBrowser('chromium')
  const tab = await openTab(browser, 'https://google.com/ncr')

  const searchInput = await findElement(tab, '[name="q"]')
  await fillInElement(searchInput, 'Node.js')

  const searchButton = await findElement(tab, `input[value="I'm Feeling Lucky"]`)
  await clickElement(searchButton)
  await waitForNavigation(tab)

  const title = await evalInTab(tab, [], 'return document.title')
  console.log(title)

  await closeBrowser(browser)
}

run()

Usage

Installation

npm Package

Install puppet-strings by running

yarn add puppet-strings

Or, if yarn is not installed, run

npm install --save puppet-strings

Locally Installed Browsers

puppet-strings works with locally installed recent stable versions of Google Chrome, Chromium, and Electron on Linux, Docker, OSX, and Windows.

We also maintain vinsonchuong/javascript, a Docker image that includes the latest Current version of Node.js and Chrome (as google-chrome)

API

puppet-strings provides an interface consisting of three nouns (browser, tab, and element) and actions that take one of them as first argument. Each action returns a promise that is resolved when the action is finished.

Here are the actions puppet-strings provides:

Browser

• openBrowser: Open a locally installed browser
• closeBrowser: Closes a browser

Tab

• getTabs: Gets the list of currently open tabs
• openTab: Opens a url in a new tab and waits for it to fully load
• closeTab: Closes a tab
• resizeTab: Changes the size of the viewport of a tab
• navigate: Navigates a tab to a new URL
• waitForNavigation: Waits for a page load to complete
• evalInTab: Evaluates code within a tab and returns the result
• findElement: Find a DOM element on the page by CSS selector

Element

• clickElement: Click on an element
• fillInElement: Type text into an element
• selectFiles: Select files for a file input element

Extension

puppet-strings is designed to be open for extension but closed for modification.

You can create new actions that take a Browser, Tab, or Element as argument. Your new actions can reuse other actions and interact directly with the underlying Puppeteer objects.

If your project needs to modify an action provided by puppet-strings, you can duplicate that action and maintain your modifications as part of your project.

Published Extensions

• openChrome(): Find or download a suitable version of Chrome for use with puppet-strings
• openApp(): Compile and open a web application in Chrome