puppet

🎭 Puppet

Natural-language web automation using Puppeteer.

⭐️ 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 [e-mail]
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

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

• Code: MIT © Anand Chowdhary
• Landing page copy: CC-BY 4.0 Puppet
• Icon: CC-BY 3.0 Jon Trillana
• Illustrations: CC-0 Pablo Stanley