Kevin Veen-Birkenbach
5e9da6dc63
- add replay target to Makefile - introduce scripts/replay.sh for headless test execution - document replay workflow in README - clarify requirements and Arch Linux setup https://chatgpt.com/share/6984a4ca-1118-800f-88f9-1bd0146e922d
163 lines
3.1 KiB
Markdown
163 lines
3.1 KiB
Markdown
# 🎭 playwright-recorder
|
||
|
||
> A small, reproducible Playwright **recording / codegen tool**
|
||
> built around **Docker**, **X11/XWayland**, and **ephemeral workspaces**
|
||
|
||
🔗 Homepage: https://github.com/kevinveenbirkenbach/playwright-recorder
|
||
|
||
---
|
||
|
||
## ✨ What is this?
|
||
|
||
`playwright-recorder` is a **developer tool** for recording Playwright tests via
|
||
the official Playwright **codegen** feature — without polluting your project:
|
||
|
||
- 🎥 **GUI-based recording** (Playwright Inspector)
|
||
- 🧼 **Always fresh** (no reused state, no lockfile pain)
|
||
- 🐳 **Runs fully in Docker**
|
||
- 🗂️ **Repo-local, git-ignored workspace**
|
||
- 📄 **Only generated tests are persisted**
|
||
- 🚫 **No `/tmp` usage**
|
||
|
||
Perfect for:
|
||
- recording login flows
|
||
- capturing UI regressions
|
||
- generating first test drafts
|
||
- infra-heavy projects where Playwright does *not* belong in the main repo
|
||
|
||
---
|
||
|
||
* `recordings/` is **ignored by git**
|
||
* `.gitkeep` ensures the folder exists
|
||
* ephemeral workspace lives in `recordings/.work/` and is auto-cleaned
|
||
|
||
---
|
||
|
||
## 🚀 Usage
|
||
|
||
### 1️⃣ Requirements
|
||
|
||
- Docker
|
||
- X11 or XWayland (Wayland-only will NOT work)
|
||
- `xhost`
|
||
|
||
On Arch Linux:
|
||
|
||
```bash
|
||
sudo pacman -S --needed xorg-xhost
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ Installation (one-time)
|
||
|
||
Prepare the recorder script:
|
||
|
||
```bash
|
||
make install
|
||
```
|
||
|
||
This makes `scripts/codegen.sh` executable.
|
||
|
||
---
|
||
|
||
## 🎥 Start recording
|
||
|
||
```bash
|
||
make codegen
|
||
```
|
||
|
||
Or with a start URL:
|
||
|
||
```bash
|
||
./scripts/codegen.sh https://example.com/login
|
||
```
|
||
|
||
---
|
||
|
||
## ▶ Replay recorded tests (headless)
|
||
|
||
Run all recorded tests:
|
||
|
||
```bash
|
||
make replay
|
||
```
|
||
|
||
Run a specific test file:
|
||
|
||
```bash
|
||
./scripts/replay.sh recordings/login.spec.ts
|
||
```
|
||
|
||
Replay runs **headless**, without X11, and does **not** require `xhost`.
|
||
|
||
---
|
||
|
||
## 📤 Output
|
||
|
||
* 📄 Generated test:
|
||
|
||
```text
|
||
recordings/codegen.spec.ts
|
||
```
|
||
|
||
* 🧼 Ephemeral workspace (auto-deleted):
|
||
|
||
```text
|
||
recordings/.work/
|
||
```
|
||
|
||
Nothing else touches your repo.
|
||
|
||
---
|
||
|
||
## ⚙️ Configuration (optional)
|
||
|
||
Environment variables:
|
||
|
||
| Variable | Default | Description |
|
||
| -------------------- | ----------------- | ------------------- |
|
||
| `PLAYWRIGHT_VERSION` | `1.58.1` | Playwright version |
|
||
| `PLAYWRIGHT_IMAGE` | auto | Docker image tag |
|
||
| `RECORDINGS_DIR` | `recordings` | Output directory |
|
||
| `OUTPUT_FILE` | `codegen.spec.ts` | Generated file name |
|
||
| `TARGET` | `playwright-test` | Codegen target |
|
||
| `DISPLAY` | `:0` | X11 display |
|
||
|
||
Example:
|
||
|
||
```bash
|
||
OUTPUT_FILE=login.spec.ts make codegen
|
||
```
|
||
|
||
---
|
||
|
||
## 🧠 Design philosophy
|
||
|
||
* ❌ Not a test runner
|
||
* ❌ Not CI tooling
|
||
* ❌ Not framework glue
|
||
* ✅ A **focused recording utility**
|
||
* ✅ One job, done well
|
||
|
||
---
|
||
|
||
## 🔐 Security note
|
||
|
||
`xhost +local:docker` is used **temporarily** to allow GUI access.
|
||
Access is **revoked automatically** when the script exits.
|
||
|
||
---
|
||
|
||
## 🧑💻 Author
|
||
|
||
Kevin Veen-Birkenbach
|
||
📧 [kevin@veen.world](mailto:kevin@veen.world)
|
||
🏡 [www.veen.world](https://www.veen.world)
|
||
|
||
---
|
||
|
||
## 📜 License
|
||
|
||
MIT License – see [LICENSE](LICENSE)
|