https://github.com/iocrafts/puppetchef
A tool that uses Puppeteer to execute web automation recipes defined in YAML format.
https://github.com/iocrafts/puppetchef
automation puppeteer web yaml
Last synced: 4 months ago
JSON representation
A tool that uses Puppeteer to execute web automation recipes defined in YAML format.
- Host: GitHub
- URL: https://github.com/iocrafts/puppetchef
- Owner: iocrafts
- License: mit
- Created: 2025-03-13T21:41:10.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-23T17:23:57.000Z (4 months ago)
- Last Synced: 2026-02-24T00:50:37.624Z (4 months ago)
- Topics: automation, puppeteer, web, yaml
- Language: JavaScript
- Homepage: https://www.iocrafts.com/projects/puppetchef/
- Size: 1.87 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Puppetchef
A web automation tool that uses Puppeteer to execute web automation recipes defined in YAML format.
## Features
- **YAML-based Recipe Definition**: Write your web automation tasks in a simple, readable YAML format (syntax inspired by Ansible). Built-in support for ENV variables and JSON objects.
- **Schema Validation**: Built-in validation for recipe structure and operations.
- **Plugin System**: Extend functionality with custom plugins.
- **Configuration Management**: Flexible configuration through JSON files.
- **Verbose Logging**: Detailed execution logs for debugging.
- **Syntax Check Mode**: Validate recipes without executing them.
- **Common Plugins and Commands**: Built-in plugins and commands for easier automation.
## Installation
```bash
npm install puppetchef
```
## Usage
```bash
puppetchef [options]
```
### Command Line Options
- ``: Recipe file in YAML format (required).
- `-c, --conf `: Configuration file (default: `puppetchefrc`).
- `--syntax-check`: Validate recipe only, without executing (default: `false`).
### Environment Variables
- `PUPPETCHEF_LOGLEVEL`: Enables debugging at the specified level (info, debug, error, warn, verbose).
- `PUPPETCHEF_LOGFILE`: Path to the log file (default: stdout) when a debug level is set.
### Examples
```bash
# Basic usage with a recipe file
puppetchef recipe.yaml
# With configuration file
puppetchef recipe.yaml -c config.json
# Validate recipe without executing
puppetchef recipe.yaml --syntax-check
```
### Configuration File (puppetchefrc)
Create a JSON configuration file to customize browser behavior:
```json
{
"executablePath": "/usr/local/bin/chromium",
"headless": false,
"defaultViewport": {
"width": 1920,
"height": 1080
},
"downloadBehavior": {
"policy": "allow",
"downloadPath": "/tmp"
}
}
```
### Recipe Format
Template engine is based on Handlebarjs and support `env` and `json` as helper functions.
```yaml
url: "https://example.com"
name: "Login Test"
tasks:
- name: "Login"
steps:
- puppetchef.builtin.common:
command: "fill_out"
selector: "#username"
data: "testuser"
- puppetchef.builtin.common:
command: "fill_out"
selector: "#password"
data: "{{{ env 'PASS' }}}"
- puppetchef.builtin.common:
command: "click"
selector: "#submit"
```
### Plugins
Create a *plugins* module with custom plugins to extend functionality:
```javascript
// plugin.js
module.exports = {
customAction: async (page, data = {}) => {
// Custom automation logic
await page.locator(data.selector);
// If you need to return values for later use
return { x: 20, y: "msg" };
}
};
```
Install the *plugins* module:
```bash
npm install plugins
```
And use it in your recipe:
```yaml
name: Example Recipe
url: https://example.com/demo-url
tasks:
- name: "Custom Action"
steps:
- puppetchef.plugins.plugin:
command: "customAction"
selector: "#username"
# Make the return value of customAction available to the following steps
register: ret
- puppetchef.builtin.common:
command: debug
format: "Debugging: {{ ret.y }}"
# Conditionals for when to execute this step
when: "{{ ret.x }} > 0"
```
## License
MIT