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

``txt
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:

`bash
puppet "path/to/download.puppet"
`

💡 Usage

$3

Install the package globally from npm:

`bash
npm install --global puppet
`

`bash


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"
`

$3

Import and use the API:

`ts
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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

`bash
npm run build
`

Run unit tests and view coverage:

`bash
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