Metadata-Version: 2.4
Name: playforge
Version: 1.0.1
Summary: A Playwright recorder that turns browser actions into reusable Page Object code.
Author-email: "ytcalifax (98w)" <hello@98w.eu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ytcalifax/playforge
Project-URL: Repository, https://github.com/ytcalifax/playforge.git
Project-URL: Bug Tracker, https://github.com/ytcalifax/playforge/issues
Project-URL: Changelog, https://github.com/ytcalifax/playforge/blob/main/CHANGELOG.md
Keywords: playwright,page-object,recorder,testing,automation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: playwright>=1.62.0.0
Requires-Dist: ruff>=0.16.4.0
Requires-Dist: structlog>=26.1.0.0
Dynamic: license-file

# 🎭 PlayForge

> **A Playwright recorder that turns browser actions into reusable Page Object code.**

PlayForge records clicks, fills, selects, and reads from a browser session, then writes the result out as Python code you can keep using. It is meant for the boring part of browser automation: set up a page, click through the flow once, and get a generated page object you can reuse instead of hand-writing locators over and over.

The project is designed to run as a normal CLI after installation. Install it globally, point it at a URL, interact with the page, and let it capture the flow. When you quit, it writes the generated code to disk.

## ✨ Features

- **🎬 Browser Recording**: Capture real user actions from a live page, including clicks, fills, selects, and text reads.
- **🧩 Page Object Generation**: Turn recorded workflows into Python page objects with reusable methods.
- **🧹 Workflow Splitting**: Split one recording session into multiple generated methods when a flow gets too long.
- **🪵 Structured Logging**: Uses `structlog` for simple, consistent CLI and runtime logs.
- **⚡ CLI Ready**: Install it globally and run `playforge --help` or `playforge <url>`.

## 📥 Installation

```bash
pip install playforge
playwright install
```

Or, to install directly from source:

```bash
pip install .
playwright install
```

If you want to use it from a local checkout while developing, install it in editable mode:

```bash
pip install -e .
playwright install
```

You need `playwright install` so Playwright downloads an actual browser. Without that, the CLI can install fine but has nothing to launch.

## 🚀 Quick Start

```bash
playforge https://example.com
```

The recorder opens a browser window, waits for you to interact with the page, and collects actions until you quit. Use `split` in the terminal if you want to break the recording into another generated method.

### Help

```bash
playforge --help
```

### Output file

```bash
playforge https://example.com -o generated_page.py
```

### What gets recorded

PlayForge watches for:

- clicks on buttons, links, and other interactive elements
- fills on input fields and text areas
- select changes
- double-click reads on readable text elements

Each captured workflow becomes a method in the generated page object. Repeated actions are collapsed where possible so the output stays usable instead of turning into a wall of duplicate steps.

## 🐍 Requirements

- Python **3.10+**
- `playwright`
- `structlog`
- `ruff`

## 🤝 Contributing

Issues and pull requests are welcome. If you hit a weird recorder edge case, open an issue with the page flow and the generated output.

---
*Built with ❤️ for browser automation and code generation. MIT Licensed.*
