### Complete Workflow Example

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/EVAL_GUIDE.md

A full example demonstrating starting a session, navigating, capturing snapshots, and taking screenshots.

```clojure
(spel/start! {:viewport {:width 1280 :height 800}})

(println (spel/help "snapshot"))

(spel/navigate "https://news.ycombinator.com")
(spel/wait-for-load-state)
(println "Title:" (spel/title) "URL:" (spel/url))

(let [snap (spel/capture-snapshot)]
  (spit "/tmp/hn-snapshot.txt" (:tree snap))
  (spel/save-annotated-screenshot! (:refs snap) "/tmp/hn-annotated.png")
  (println "Refs:" (count (:refs snap))))

(spel/screenshot {:path "/tmp/hn-plain.png"})
(spel/stop!)
```

--------------------------------

### Full Pipeline Example

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/PDF_STITCH_VIDEO.md

Demonstrates a complete workflow from starting video recording, performing actions, exporting logs and subtitles, to post-processing the video with FFmpeg and adding narration.

```APIDOC
## Full Pipeline Example

### Description
This example showcases a comprehensive workflow using Spel and FFmpeg, from initiating video recording to generating a final narrated video file.

### Steps
1. **Start Video Recording:** Initiate recording with specified dimensions.
2. **Clear Action Log:** Reset the action log.
3. **Perform Actions:** Navigate, scroll, and click on elements, with human pauses in between.
4. **Finish Video Recording:** Save the recorded video.
5. **Export Action Log as SRT:** Generate SRT subtitles from the action log.
6. **Trim Video:** Remove idle frames and set frame rate.
7. **Burn-in Subtitles:** Combine the trimmed video with subtitles.
8. **Add Narration:** Append an audio narration track.

### Bash Script Example
```bash
set -e

# Start recording and perform actions
spel eval-sci '
  (spel/start-video-recording {:video-size {:width 1920 :height 1080}})
  (spel/clear-action-log!)
  (spel/navigate "https://example.org") (spel/human-pause)
  (spel/smooth-scroll 500)               (spel/human-pause)
  (spel/click "a")                       (spel/human-pause 500 1000)
  (spel/finish-video-recording {:save-as "/tmp/session.webm"})
'

# Export action log to SRT
spel action-log --srt -o /tmp/session.srt

# Trim and re-encode video
ffmpeg -i /tmp/session.webm -vf "mpdecimate,setpts=N/30/TB" -r 30 /tmp/trimmed.mp4

# Burn subtitles into the video
ffmpeg -i /tmp/trimmed.mp4  -vf "subtitles=/tmp/session.srt" -c:a copy /tmp/final.mp4

# Add narration (assuming 'say' command is available)
say -o /tmp/narration.aiff "Welcome to the demo."
ffmpeg -i /tmp/final.mp4 -i /tmp/narration.aiff -c:v copy -c:a aac -shortest /tmp/narrated.mp4
```
```

--------------------------------

### Initialize Spel testing environment

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CONSTANTS.md

Examples for starting a standalone session, using the testing page library, or setting viewport dimensions in daemon mode.

```clojure
(spel/start! {:device :iphone-14})                         ; standalone
(core/with-testing-page {:device :iphone-14} [pg] …)       ; library
(spel/set-viewport-size! 390 844)                          ; daemon mode, viewport only
```

--------------------------------

### Native Image Installation

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CODEGEN_CLI.md

Commands to build and install the native binary.

```bash
clojure -T:build uberjar
clojure -T:build native-image
./target/spel install
```

--------------------------------

### Install Browsers and Verify Spel

Source: https://github.com/blockether/spel/blob/main/README.md

After installing the Spel CLI, run 'spel install' to download necessary browsers and 'spel version' to confirm the installation.

```bash
spel install   # install browsers
spel version   # verify installation
```

--------------------------------

### Snapshot Output Example

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CODEGEN_CLI.md

Example output format for the snapshot command.

```text
- heading "Example Domain" [@e2yrjz] [level=1]
- link    "More information..." [@e9mter]
- button  "Submit" [@e6t2x4]
```

--------------------------------

### Manage browser installations

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CODEGEN_CLI.md

Commands for installing browsers and their dependencies, as well as performing one-off browser tasks.

```bash
spel install                        # install browsers (Chromium default)
spel install --with-deps chromium   # + system dependencies
spel codegen URL                    # record interactions
spel open URL                       # open browser
spel screenshot URL                 # take screenshot
```

--------------------------------

### Complete Spel Example

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/SELECTORS_SNAPSHOTS.md

A comprehensive example demonstrating navigation, snapshot capture, annotated screenshots, action markers, interaction, and final assertions. This workflow covers a typical testing scenario.

```clojure
(spel/navigate "https://news.ycombinator.com")
(spel/wait-for-load-state)

(def snap (spel/capture-snapshot))
(println (:tree snap))
(spel/save-annotated-screenshot! (:refs snap) "/tmp/hn-annotated.png")

(spel/inject-action-markers! "@e9mter")
(spel/screenshot {:path "/tmp/hn-before-click.png"})
(spel/remove-action-markers!)

(spel/click "@e9mter")
(spel/wait-for-load-state)

(spel/assert-visible "h1")
(println "Now at:" (spel/url))
(spel/save-audit-screenshot! "After clicking first link" "/tmp/hn-result.png")
```

--------------------------------

### Complete Workflow Example

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CODEGEN_CLI.md

A full sequence of commands demonstrating a typical automation flow.

```bash
spel open https://example.org
spel snapshot -i
spel screenshot initial.png
spel get title
spel get url
spel get text @e9mter
spel is visible @e6t2x4
spel click @e9mter
spel snapshot -i
spel network requests
spel close
```

--------------------------------

### Install Spel CLI on Windows

Source: https://github.com/blockether/spel/blob/main/README.md

Download and install the Spel CLI binary for Windows. It will be placed in your local app data directory.

```powershell
# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/Blockether/spel/releases/latest/download/spel-windows-amd64.exe -OutFile spel.exe
Move-Item spel.exe "$env:LOCALAPPDATA\Microsoft\WindowsApps\spel.exe"
```

--------------------------------

### Execute Tests and REPL

Source: https://github.com/blockether/spel/blob/main/README.md

Commands to run the test suite or start the development environment.

```makefile
make test
make test-allure
```

```makefile
make repl
```

--------------------------------

### Configure viewport presets

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CONSTANTS.md

Examples for setting viewport dimensions using predefined keywords or custom width and height maps.

```clojure
(core/with-testing-page {:viewport :desktop-hd}            [pg] …)
(core/with-testing-page {:viewport {:width 1440 :height 900}} [pg] …)
```

--------------------------------

### Register Build Start for CI Progress Tracking

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CODEGEN_CLI.md

Call this function to indicate the start of a CI build. It shows a yellow animated badge before tests complete. Requires site directory, run number, commit details, and URLs.

```clojure
(ci/register-build-start! {:site-dir "gh-pages-site" :run-number "123" :commit-sha "abc…"
                           :commit-msg "feat: add feature" :commit-author "dev"
                           :repo-url "https://github.com/org/repo"
                           :run-url "https://github.com/org/repo/actions/runs/456"})
```

--------------------------------

### Install Spel Agents

Source: https://github.com/blockether/spel/blob/main/README.md

Use `spel install` to download Chromium. If Edge was chosen, run `spel install msedge` as well. This command is essential for setting up the necessary browser components for Spel.

```bash
spel install
```

```bash
spel install msedge
```

--------------------------------

### Install Spel CLI on Linux (amd64)

Source: https://github.com/blockether/spel/blob/main/README.md

Download and install the Spel CLI binary for Linux (amd64). Ensure the binary is executable and in your PATH.

```bash
# Linux (amd64)
curl -LO https://github.com/Blockether/spel/releases/latest/download/spel-linux-amd64
chmod +x spel-linux-amd64 && mv spel-linux-amd64 ~/.local/bin/spel
```

--------------------------------

### Install Spel CLI on Linux (arm64)

Source: https://github.com/blockether/spel/blob/main/README.md

Download and install the Spel CLI binary for Linux (arm64). Ensure the binary is executable and in your PATH.

```bash
# Linux (arm64)
curl -LO https://github.com/Blockether/spel/releases/latest/download/spel-linux-arm64
chmod +x spel-linux-arm64 && mv spel-linux-arm64 ~/.local/bin/spel
```

--------------------------------

### Comprehensive Spel Test Example

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/flavours/lazytest/testing-conventions.md

An example test case demonstrating the use of `defdescribe`, `describe`, `it`, `core/with-testing-page`, navigation, and assertions including exact string matching and checking for absence of text.

```clojure
(ns my-app.test
  (:require
   [com.blockether.spel.assertions :as assert]
   [com.blockether.spel.core :as core]
   [com.blockether.spel.locator :as locator]
   [com.blockether.spel.page :as page]
   [com.blockether.spel.roles :as role]
   [com.blockether.spel.allure :refer [defdescribe describe expect it]]))

(defdescribe my-test
  (describe "example.org"

    (it "navigates and asserts"
      (core/with-testing-page [page]
        (page/navigate page "https://example.org")
        (expect (= "Example Domain" (page/title page)))
        (expect (nil? (assert/has-text (assert/assert-that (page/locator page "h1")) "Example Domain")))))))
```

--------------------------------

### Verify Spel Installation

Source: https://github.com/blockether/spel/blob/main/README.md

Confirm the Spel installation by checking the version and testing basic functionality. This includes opening a URL and closing the browser session.

```bash
spel version
```

```bash
spel open https://example.com
```

```bash
spel close
```

--------------------------------

### Page Setup with Options

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/flavours/lazytest/testing-conventions.md

Configures the Playwright page context with specific options like device, viewport, or locale for testing. Demonstrates setting a device and checking the navigator language.

```clojure
;; With options (device, viewport, locale, etc.)
(core/with-testing-page {:device :iphone-14} [page]
  (page/navigate page "https://example.org")
  (expect (= "fr-FR" (page/evaluate page "navigator.language"))))
```

```clojure
;; Desktop HD viewport with locale
(core/with-testing-page {:viewport :desktop-hd :locale "fr-FR"} [page]
  (page/navigate page "https://example.org"))
```

```clojure
;; Firefox with visible browser
(core/with-testing-page {:browser-type :firefox :headless false} [page]
  (page/navigate page "https://example.org"))
```

```clojure
;; Load saved auth state
(core/with-testing-page {:storage-state "auth.json"} [page]
  (page/navigate page "https://app.example.org/dashboard"))
```

--------------------------------

### Configure Spel agent safety flags

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/SKILL.md

Example of running the Spel agent with content boundaries, output limits, and domain allowlisting enabled.

```bash
spel --content-boundaries --max-output 50000 \
     --allowed-domains "example.com,*.example.com" \
     open https://example.com
```

--------------------------------

### Install Spel CLI on macOS

Source: https://github.com/blockether/spel/blob/main/README.md

Download and install the Spel CLI binary for macOS (Apple Silicon). Ensure the binary is executable and in your PATH.

```bash
# macOS (Apple Silicon)
curl -LO https://github.com/Blockether/spel/releases/latest/download/spel-macos-arm64
chmod +x spel-macos-arm64 && mv spel-macos-arm64 ~/.local/bin/spel
```

--------------------------------

### Spel Stealth Mode CLI Examples

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/PROFILES_AGENTS.md

Examples of using Spel's stealth mode via the command line. Stealth mode is enabled by default to evade detection. Use --no-stealth to disable.

```bash
spel open https://example.org                             # stealth auto
```

```bash
spel --profile /path/to/profile open https://protected-site.com
```

```bash
spel --channel chrome --profile ~/.config/google-chrome/Profile\ 1 open https://x.com
```

```bash
spel --no-stealth open https://example.org                # off
```

--------------------------------

### Manual CDP Session Setup

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/AGENT_COMMON.md

Manual configuration for connecting to a specific browser profile via a remote debugging port.

```bash
SESSION="exp-$(date +%s)"
CDP_PORT=$(spel find-free-port)
open -na "Google Chrome" --args --remote-debugging-port=$CDP_PORT \
     --user-data-dir="/tmp/spel-cdp-$SESSION" --no-first-run
spel --session $SESSION --cdp http://127.0.0.1:$CDP_PORT open https://example.com
```

--------------------------------

### Basic Page Setup with with-testing-page

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/flavours/lazytest/testing-conventions.md

Sets up the Playwright stack (playwright, browser, context, page) for basic navigation and title assertion. Tracing and HAR are enabled when Allure is active.

```clojure
;; Basic usage
(core/with-testing-page [page]
  (page/navigate page "https://example.org")
  (expect (= "Example Domain" (page/title page))))
```

--------------------------------

### Navigate and Interact with SpEL CLI

Source: https://github.com/blockether/spel/blob/main/README.md

Use these commands to open URLs, click elements, fill forms, press keys, and take screenshots. The first command starts a background daemon.

```bash
spel open https://example.org             # open a page
spel click "text=More information"        # click a link by text
spel fill "#search" "browser automation"  # fill an input field
spel press Enter                          # press a key
spel screenshot result.png                # take a screenshot
spel close                                # close the session
```

--------------------------------

### Run clojure.test with Allure Reporter

Source: https://github.com/blockether/spel/blob/main/CLAUDE.md

Example of setting up and running a clojure.test test case with Allure reporting for agent development. Ensure the :test-ct alias is configured for execution.

```clojure
(ns my-app.test
  (:require [clojure.test :refer [deftest testing is]]
            [com.blockether.spel.allure :as allure]
            [com.blockether.spel.core :as core]))

(deftest my-test
  (allure/epic "My Epic")
  (testing "something"
    (core/with-testing-page [pg]
      (is (= 1 1)))))
```

--------------------------------

### Record smooth video with SRT subtitles

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/PDF_STITCH_VIDEO.md

A complete example demonstrating Spel's video recording capabilities, including clearing the action log, navigating, smooth scrolling, clicking, exporting SRT subtitles, and finishing the recording.

```clojure
(spel/start-video-recording {:video-size {:width 1920 :height 1080}})
```

```clojure
(spel/clear-action-log!)
```

```clojure
(spel/navigate "https://example.org") (spel/human-pause)
```

```clojure
(spel/smooth-scroll 300)                 (spel/human-pause)
```

```clojure
(spel/click "a")                         (spel/human-pause 500 1000)
```

```clojure
(spit "/tmp/session.srt" (spel/export-srt))
```

```clojure
(spel/finish-video-recording {:save-as "/tmp/session.webm"})
```

--------------------------------

### Video Recording and FFmpeg Post-processing

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/PDF_STITCH_VIDEO.md

Example of starting and finishing video recording with Spel, and using FFmpeg for post-processing tasks like burning in subtitles, styling them, trimming, and adjusting speed.

```APIDOC
## Spel Clojure API - Video Recording

### Description
Functions to control video recording sessions.

### Functions
- `(spel/start-video-recording {:video-size {:width <w> :height <h>}})`: Starts video recording with specified dimensions.
- `(spel/finish-video-recording {:save-as <filename.webm>})`: Finishes video recording and saves to the specified file.

## FFmpeg Post-processing Examples

### Description
Examples of using FFmpeg to enhance recorded videos.

### Commands
- **Burn in subs (hard subs):**
  ```bash
  ffmpeg -i session.webm -vf "subtitles=session.srt" -c:a copy output.mp4
  ```
- **Styled subs:**
  ```bash
  ffmpeg -i session.webm \
    -vf "subtitles=session.srt:force_style='FontSize=18,PrimaryColour=&HFFFFFF&,BackColour=&H80000000&,BorderStyle=4'" \
    -c:a copy output.mp4
  ```
- **Remove idle frames and re-encode at 30fps:**
  ```bash
  ffmpeg -i session.webm -vf "mpdecimate,setpts=N/30/TB" -r 30 trimmed.mp4
  ```
- **Speed up video (2x):**
  ```bash
  ffmpeg -i session.webm -vf "setpts=0.5*PTS" -af "atempo=2.0" fast.mp4
  ```
- **Slow down video (0.5x):**
  ```bash
  ffmpeg -i session.webm -vf "setpts=2.0*PTS" -af "atempo=0.5" slow.mp4
  ```
- **Concatenate videos:**
  ```bash
  printf "file 'a.mp4'\nfile 'b.mp4'\n" > list.txt
  ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4
  ```
```

--------------------------------

### Get Signature and Documentation for a Specific Function

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CODEGEN_CLI.md

To retrieve the signature and documentation for a single function, use `spel/help` with the fully qualified function name. Example: `(spel/help "spel/click")`.

```clojure
(spel/help "spel/click")
```

--------------------------------

### Common AriaRole Usage Examples

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CONSTANTS.md

Examples of common role-based selector patterns.

```clojure
(spel/get-by-role role/button {:name "Save"})
(spel/get-by-role role/link {:name "Home"})
(spel/get-by-role role/heading {:level 2})
(spel/get-by-role role/textbox {:name "Email"})
(spel/get-by-role role/checkbox {:name "Agree"})
(spel/get-by-role role/combobox {:name "Country"})
(spel/get-by-role role/navigation)
(spel/get-by-role role/dialog {:name "Confirm"})
(spel/get-by-role role/table)
(spel/get-by-role role/tab {:name "Settings"})
```

--------------------------------

### Initialize AI Agent Prompts

Source: https://github.com/blockether/spel/blob/main/README.md

Generates instruction files for AI coding agents to understand Spel commands and workflows.

```bash
# Generate prompt files for Claude Code:
spel init-agents --loop=claude

# Generate prompt files for OpenCode (default):
spel init-agents
```

--------------------------------

### Install Playwright Browsers

Source: https://github.com/blockether/spel/blob/main/README.md

Installs required browsers and dependencies using the Playwright Java CLI via Clojure.

```clojure
clojure -M -e "(com.microsoft.playwright.CLI/main (into-array String [\"install\" \"--with-deps\"]))"
```

--------------------------------

### Discover API documentation

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/EVAL_GUIDE.md

Use the help function to list namespaces, search for keywords, or view specific function signatures.

```clojure
(spel/help)                  ; list namespaces + counts
(spel/help "spel")           ; list every fn in one namespace with signatures + docs
(spel/help "screenshot")     ; keyword search across namespaces
(spel/help "spel/click")     ; one fn's signature + doc
```

--------------------------------

### Project Build and Test Commands

Source: https://github.com/blockether/spel/blob/main/CLAUDE.md

Standard Makefile commands for testing, formatting, linting, and building the project locally.

```bash
make test                    # ALL: lazytest + CLI bash
make test-cli                # CLI bash only
make test-cli-clj            # CLI Clojure integration only
make format                  # auto-format
make lint                    # clojure-lsp --raw
make validate-safe-graal     # reflection/boxed-math check
make gen-docs                # regen FULL_API.md (before install-local)
make install-local           # uberjar → native-image → ~/.local/bin/spel
make init-agents ARGS="--ns com.blockether.spel --force"  # regen 8 agents
clojure -M:test-ct           # clojure.test + Allure (test/ct/)
```

--------------------------------

### Record browser video

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/PDF_STITCH_VIDEO.md

Starts and finishes video recording for a browser session. Note that starting a recording resets the page context.

```clojure
(spel/start-video-recording)
(spel/navigate "https://example.org")
(spel/wait-for-load-state)
;; ... actions ...
(spel/finish-video-recording {:save-as "/tmp/session.webm"})
```

```clojure
(spel/video-path)                                          ;; current file or nil
(spel/finish-video-recording {:save-as "/tmp/demo.webm"})  ;; stop + copy
(spel/finish-video-recording)                              ;; stop, keep in :video-dir
```

--------------------------------

### Configure Advanced PDF Options

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/PDF_STITCH_VIDEO.md

Demonstrates usage of header/footer templates and layout configuration for PDF generation.

```clojure
(spel/pdf {:path "/tmp/report.pdf" :format "A4" :landscape true
           :print-background true :scale 0.8 :page-ranges "1-5"
           :display-header-footer true
           :header-template "<div style='font-size:10px;text-align:center;width:100%'>My Report</div>"
           :footer-template "<div style='font-size:10px;text-align:center;width:100%'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>"})
```

--------------------------------

### List All Namespaces and Function Counts

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CODEGEN_CLI.md

Use `spel/help` without arguments to list all available namespaces and the number of functions within each. This is useful for initial API exploration.

```clojure
(spel/help)
```

--------------------------------

### Execute local build and test commands

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CI_WORKFLOWS.md

Common commands for testing, linting, and building the project locally.

```bash
make test
make lint
make validate-safe-graal
./verify.sh

clojure -T:build jar
clojure -T:build native-image
clojure -T:build uberjar

make test-cli
make test-cli-clj
```

--------------------------------

### CLI Bash Scripting for Testing

Source: https://github.com/blockether/spel/blob/main/CLAUDE.md

Illustrates common patterns for writing bash scripts to test CLI commands and daemon actions. Includes assertions for JSON output and text content, temporary file management, and ensuring commands have help flags.

```bash
section "Name (N)"
assert_jq/assert_jq_eq/assert_jq_contains for --json
assert_contains for text (e.g. --help)
TEMP_FILES+=("path") for cleanup
"$SPEL" not $SPEL
```

--------------------------------

### Interacting with JDK Classes

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/EVAL_GUIDE.md

Demonstrates using registered JDK classes such as Base64 and System.

```clojure
(let [enc (java.util.Base64/getEncoder)
      dec (java.util.Base64/getDecoder)]
  (->> (.getBytes "hello") (.encodeToString enc) (.decode dec) (String.)))    ; => "hello"

(System/getenv "HOME")
(System/currentTimeMillis)
(Thread/sleep (long 500))                ; non-browser delays only — see tip below
```

--------------------------------

### Generated Clojure Test Code Example

Source: https://context7.com/blockether/spel/llms.txt

An example of Clojure test code automatically generated from a browser recording. It includes necessary requires for Spel core, page, and locator functionalities, and uses `with-testing-page` to set up the browser context.

```clojure
;; Generated test code example
(ns my-app.e2e
  (:require [com.blockether.spel.core :as core]
            [com.blockether.spel.page :as page]
            [com.blockether.spel.locator :as locator]))

(core/with-testing-page [pg]
  (page/navigate pg "https://example.org")
  (locator/click (page/get-by-text pg "More information"))
  (page/wait-for-load-state pg))
```

--------------------------------

### Iterate over locators

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/PAGE_LOCATORS.md

Example of iterating over multiple elements using the all function.

```clojure
(doseq [item (locator/all (page/locator pg ".todo-item"))] …)
```

--------------------------------

### Initialize browser stack with with-testing-page

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/BROWSER_OPTIONS.md

Use this macro to create the full Playwright stack in a single step. It supports various configurations including device presets and persistent profiles.

```clojure
(core/with-testing-page [pg]
  (page/navigate pg "https://example.org")
  (page/title pg))

(core/with-testing-page {:device :iphone-14} [pg] ...)
(core/with-testing-page {:viewport :desktop-hd :locale "fr-FR"} [pg] ...)
(core/with-testing-page {:browser-type :firefox :headless false} [pg] ...)
(core/with-testing-page {:profile "/tmp/my-chrome-profile"} [pg] ...)      ; persistent
(core/with-testing-page {:executable-path "/usr/bin/chromium" :args ["--disable-gpu"]} [pg] ...)
```

--------------------------------

### Device and Viewport Configuration

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CONSTANTS.md

Methods for initializing testing environments using device keywords or custom viewport sizes.

```APIDOC
## Device and Viewport Configuration

### Description
Configures the testing environment by specifying a device preset or custom viewport dimensions.

### Methods
- `spel/start!`: Initializes a standalone testing session.
- `core/with-testing-page`: Initializes a testing page within a library context.
- `spel/set-viewport-size!`: Sets viewport dimensions in daemon mode.

### Parameters
#### Request Body
- **device** (keyword) - Optional - A predefined device keyword (e.g., :iphone-14, :pixel-5, :ipad-pro).
- **viewport** (map/keyword) - Optional - A viewport preset keyword or a map containing :width and :height integers.

### Request Example
(spel/start! {:device :iphone-14})
(core/with-testing-page {:viewport {:width 1440 :height 900}} [pg] …)
```

--------------------------------

### Handle Cookies with eval-sci

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/AGENT_COMMON.md

Example of capturing a snapshot and conditionally accepting cookies if present.

```clojure
(let [snap (spel/capture-snapshot)]
  (when (str/includes? (:tree snap) "cookie")
    (try (spel/click (spel/get-by-role role/button {:name "Accept all"}))
         (catch Exception _ nil))
    (spel/wait-for-load)))
```

--------------------------------

### Chaining sub-selection with loc-locator

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/PAGE_LOCATORS.md

Perform nested element selection starting from an existing locator.

```clojure
(let [form (page/locator pg ".checkout-form")]
  (locator/loc-locator form "button"))

(-> (page/locator pg "nav")
    (locator/loc-locator "ul")
    (locator/loc-locator "li:first-child")
    (locator/click))
```

--------------------------------

### Configure browser launch options

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/BROWSER_OPTIONS.md

Use these functions to launch different browser engines with custom configurations like headless mode, proxies, or stealth arguments.

```clojure
(core/launch-chromium pw {:headless true})                       ; default
(core/launch-chromium pw {:headless false :slow-mo 500})         ; debug
(core/launch-chromium pw {:channel "chrome"})                    ; or "msedge", "chrome-beta", …
(core/launch-chromium pw {:args ["--disable-gpu" "--no-sandbox"]})
(core/launch-chromium pw {:ignore-default-args ["--enable-automation"]})

;; Stealth
(require '[com.blockether.spel.stealth :as stealth])
(core/launch-chromium pw {:args (stealth/stealth-args)
                          :ignore-default-args (stealth/stealth-ignore-default-args)})

;; Proxy
(core/launch-chromium pw {:proxy {:server "http://proxy:8080" :username "u" :password "p"}})

(core/launch-firefox pw {:headless true})
(core/launch-webkit  pw {:headless true})
```

--------------------------------

### Get Page Information

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CODEGEN_CLI.md

Commands to retrieve specific data from the current page or elements.

```bash
spel get url
spel get title
spel get text  @e2yrjz
spel get html  @e2yrjz
spel get value @e9mter
spel get attr  @e2yrjz href
spel get count ".items"
spel get box   @e2yrjz       # {x, y, width, height}
```

--------------------------------

### Access Playwright Java enums

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CONSTANTS.md

Direct interop examples for common Playwright enum states and configurations.

```clojure
LoadState/NETWORKIDLE      WaitUntilState/COMMIT      ColorScheme/DARK
MouseButton/RIGHT          ScreenshotType/PNG         ForcedColors/ACTIVE
ReducedMotion/REDUCE       Media/PRINT                WaitForSelectorState/HIDDEN
AriaRole/BUTTON
```

--------------------------------

### Basic Workflow Commands

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CODEGEN_CLI.md

Standard commands for opening pages, taking snapshots, and capturing screenshots.

```bash
spel open https://example.org
spel snapshot                # full a11y tree
spel screenshot page.png
```

--------------------------------

### Auto-Launch Session Pattern

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/AGENT_COMMON.md

Simplest pattern for initializing a session with automatic browser launching.

```bash
SESSION="exp-$(date +%s)"
spel --session $SESSION --auto-launch open https://example.com
spel --session $SESSION snapshot -i
spel --session $SESSION click @eXXXXX
spel --session $SESSION close
```

--------------------------------

### Keyboard Press API Reproduction

Source: https://github.com/blockether/spel/blob/main/CLAUDE.md

Examples of failed keyboard press attempts prior to the API fix.

```clojure
(spel/press "Escape")           ;; => Wrong number of args (1) passed to: sci-press
(spel/keyboard-press "Escape")  ;; => Could not resolve symbol: spel/keyboard-press
(-> (spel/page) (.keyboard) (.press "Escape"))  ;; => No matching method press found taking 1 args
```

--------------------------------

### Spel CLI Commands for Screenshots

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/SLIDE_PATTERNS.md

Demonstrates how to use the Spel command-line interface to open presentation slides and capture screenshots.

```bash
spel open $(pwd)/spel-visual/slides.html
spel screenshot $(pwd)/spel-visual/slide-01.png
spel screenshot $(pwd)/spel-visual/slide-02.png
```

--------------------------------

### Define a test with Allure metadata

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/ALLURE_REPORTING.md

Example of a test using the Allure reporter and core testing page utilities.

```clojure
(ns my-app.test
  (:require [clojure.test :refer [deftest testing is]]
            [com.blockether.spel.allure :as allure]
            [com.blockether.spel.core :as core]
            [com.blockether.spel.page :as page]))

(deftest login-test
  (allure/epic "Auth")
  (allure/feature "Login")
  (testing "loads login page"
    (core/with-testing-page [pg]
      (page/navigate pg "https://example.com/login")
      (is (= "Login" (page/title pg))))))
```

--------------------------------

### Spel API - Session and Tab Management

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/FULL_API.md

APIs for starting, stopping, and managing Playwright sessions and browser tabs.

```APIDOC
## spel/start!

### Description
Creates a new Playwright instance.

### Method
POST

### Endpoint
/spel/start!

### Parameters
#### Request Body
- **opts** (object) - Optional - Options for starting the Playwright instance.

### Response
#### Success Response (200)
- **session_id** (string) - The ID of the newly created Playwright session.

## spel/stop!

### Description
Stops the Playwright session, closing the browser and cleaning up resources.

### Method
POST

### Endpoint
/spel/stop!

### Parameters
None

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the session has stopped.

## spel/switch-tab!

### Description
Switches to the tab at the given index.

### Method
POST

### Endpoint
/spel/switch-tab!

### Parameters
#### Query Parameters
- **idx** (integer) - Required - The index of the tab to switch to.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the tab has been switched.
```

--------------------------------

### Configure Corporate Proxy

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/ENVIRONMENT_VARIABLES.md

Set CA bundle environment variables before installing dependencies to ensure compatibility with corporate proxies.

```bash
# Before running spel install
export SPEL_CA_BUNDLE=/path/to/corporate-ca.pem
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
spel install --with-deps
```

--------------------------------

### Initialize AI Agent Prompt Files

Source: https://context7.com/blockether/spel/llms.txt

Use `spel init-agents` to generate prompt files for AI coding agents like Claude Code and OpenCode. Options allow specifying agent groups, skipping test scaffolding, or customizing the test framework flavor.

```bash
# Generate prompt files for Claude Code
spel init-agents --loop=claude

# Generate for OpenCode (default)
spel init-agents

# Selective agent groups
spel init-agents --only=test           # test-writing agents only
spel init-agents --only=automation     # browser automation agents
spel init-agents --only=bugfind        # bug-finding agents
spel init-agents --only=visual         # visual QA agents
spel init-agents --only=orchestrator   # smart routing agent

# Skip test scaffolding
spel init-agents --no-tests

# Custom test framework
spel init-agents --flavour=clojure-test  # use clojure.test instead of Lazytest
```

--------------------------------

### Define E2E Test with Assertions

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/flavours/clojure-test/testing-conventions.md

Example of a full test definition using the Spel testing macros and assertion library.

```clojure
(ns my-app.e2e.seed-test
  (:require
   [clojure.test :refer [deftest testing is]]
   [com.blockether.spel.assertions :as assert]
   [com.blockether.spel.core :as core]
   [com.blockether.spel.locator :as locator]
   [com.blockether.spel.page :as page]
   [com.blockether.spel.roles :as role]))

(deftest homepage-test
  (testing "loads successfully"
    (core/with-testing-page [page]
      (page/navigate page "https://example.org")
      (is (= "Example Domain" (page/title page)))
      (is (nil? (assert/has-text (assert/assert-that (page/locator page "h1")) "Example Domain"))))))
```

--------------------------------

### Restart Spel Session

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/COMMON_PROBLEMS.md

If a previous Spel session was not properly closed, stop the old session and start a new one.

```clojure
(spel/stop!)
(spel/start!)
```

--------------------------------

### Serve Allure Reports Locally

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/ALLURE_REPORTING.md

After generating the Allure report, serve the `allure-report` directory using a local HTTP server (like `http-server`) to view the interactive HTML report. Serving via `file://` is not supported due to Service Worker requirements.

```bash
npx http-server allure-report -o -p 9999
```

--------------------------------

### Emulate Devices in Spel

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/PROFILES_AGENTS.md

Configure viewport sizes and full device presets using Clojure functions or CLI commands.

```clojure
;; Viewport only
(spel/set-viewport-size! 390 844)
(spel/navigate "https://example.org")
(spel/screenshot {:path "/tmp/mobile-view.png"})

;; Programmatic full device from SCI (keyword or name string,
;; matching is case/separator/punctuation insensitive):
(spel/set-device! :iphone-14)
(spel/set-device! "Pixel 7")
(spel/navigate "https://example.org")
(spel/screenshot {:path "/tmp/iphone14.png"})
```

```bash
# Full device preset via daemon CLI (unchanged)
spel open https://example.org
spel set device "iPhone 14"
spel screenshot /tmp/iphone14.png
```

```clojure
;; Standalone eval-sci
(spel/start! {:device :iphone-14})
(spel/navigate "https://example.org")
(spel/screenshot {:path "/tmp/iphone14.png"})
(spel/stop!)

;; Library
(core/with-testing-page {:device :pixel-7} [pg]
  (page/navigate pg "https://example.org")
  (page/screenshot pg {:path "/tmp/pixel7.png"}))
```

--------------------------------

### Configure proxy and CA certificates

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/CODEGEN_CLI.md

Set environment variables to trust corporate CA certificates when installing browsers behind an SSL-inspecting proxy.

```bash
export SPEL_CA_BUNDLE=/path/to/corporate-ca.pem
spel install --with-deps

# Or reuse Node.js var (covers driver + browser downloads)
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
spel install --with-deps
```

--------------------------------

### Record Video via CLI

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/AGENT_COMMON.md

Commands to open a session, interact with elements, and finalize a video recording.

```bash
spel --session $SESSION open <url> --interactive --record-video
spel --session $SESSION click @e123
spel --session $SESSION action-log --srt -o session.srt
spel --session $SESSION close   # finalizes video
```

--------------------------------

### Perform HTTP requests

Source: https://github.com/blockether/spel/blob/main/resources/com/blockether/spel/templates/skills/spel/references/API_TESTING.md

Executes various HTTP methods including GET, POST, PUT, PATCH, DELETE, HEAD, and custom methods.

```clojure
(core/api-get    ctx "/users"   {:params {:page 1}})
(core/api-post   ctx "/users"   {:data "{\"name\":\"Alice\"}" :headers {"Content-Type" "application/json"}})
(core/api-put    ctx "/users/1" {:data "{\"name\":\"Bob\"}"})
(core/api-patch  ctx "/users/1" {:data "{\"name\":\"Charlie\"}"})
(core/api-delete ctx "/users/1")
(core/api-head   ctx "/health")
(core/api-fetch  ctx "/resource" {:method "OPTIONS"})           ; custom
```