playwright-recorder/README.md

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

## ⚙️ 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
```

---

## 📤 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)