Anand Chowdhary
/open-source/2020
📦

Puppet

April 15, 2020
TypeScript
14 stars
2 forks
View on GitHub

🎭 Natural language web automation with Puppeteer

AnandChowdhary/puppetREADME

🎭 Puppet

Natural-language web automation using Puppeteer.

Node CI Travis CI Coverage Dependencies License Vulnerabilities Based on Node.ts npm type definitions npm package npm downloads Contributors semantic-release

npm

⭐️ How it works

Write in natural language (following the Commands section). For example, you can create a file with the following set of commands:

path/to/download.puppet:

Go to typeform.com
Click on the login link
Type username user@example.com
Type password 3rjiw9qie2308
Click on login button
Take a screenshot
Download https://admin.typeform.com/export
Save to to report.csv

Then, run the command:

puppet "path/to/download.puppet"

💡 Usage

CLI

Install the package globally from npm:

npm install --global puppet

# Local Puppet file
puppet "path/to/commands.puppet"

# Remote Puppet file
puppet https://pastebin.com/raw/AeY1MAwF

# Commands directly in CLI
puppet "open example.com" "get page HTML" "save as page.html"

API

Import and use the API:

const { puppet } = require("puppet"); // Node.js
import { puppet } from "puppet"; // TypeScript/ES6

// Local Puppet file
await puppet("path/to/commands.puppet");

// Remote Puppet file
await puppet("https://pastebin.com/raw/AeY1MAwF");

// Commands directly as an array of strings
await puppet(["open example.com", "get page HTML", "save as page.html"]);

🔫 Commands

Navigation

  • Go to example.com
  • Navigate to URL https://example.com
  • Go to the page on example.com
  • Open www.example.com

Timers

  • Wait for 10 seconds
  • Wait for 2 minutes
  • Wait for 100ms
  • Wait for navigation

Screenshot

  • Take a screenshot of this page
  • Take a JPEG screenshot
  • Full screenshot this page
  • Make a transparent screenshot
  • Screenshot and omit the background

Export page to PDF/HTML

  • Save this page as PDF
  • Save page HTML
  • Get the HTML
  • Save the whole page as PDF

Save to file

  • Save result to path/to/file
  • Save this screenshot to path/to/file
  • Save this to the file path/to/file

Mouse events

  • Click on point [123, 456]
  • Right click on coordinates 123, 456
  • Move mouse cursor to points 123, 456
  • Click on 123, 456 using middle mouse button

👩‍💻 Development

Build TypeScript:

npm run build

Run unit tests and view coverage:

npm run test-without-reporting

Related work

  • Puppeteer is the headless Chrome API for Node.js
  • Archiver is the Internet Archive saver I made using Puppeteer
  • TagUI is a CLI for digital process automation (RPA)

✨ Contributors

Thanks goes to these wonderful people (emoji key):


Anand Chowdhary
🤔 💻 ⚠️ 📖
Gajus Kuizinas
🚇

This project follows the all-contributors specification. Contributions of any kind welcome!

📄 License