btape 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7ea547bca5c9c270e16d779e170c68b0ab30b8bc4156cde58d4cfe7560ebbe4
-  data.tar.gz: fb55fff428c21bfbc889aa653708a1d02c77ffe795c515238716ad9e246fecf6
+  metadata.gz: 3f37303b9cf610d9df7cf05199599bee524a462812e328e73bfda3f003138aec
+  data.tar.gz: 62151779b2bbe5ae60c645c66e4349b6a7f6655cf6828999c3b3d1c4bba4ff73
 SHA512:
-  metadata.gz: 715e86c7d8e3d18834de6350eacac2ddad337d031faf3fae46f57d86364c445679509d9ef9db25e74688df5ac5c8c341a34418d85fb597b82ec312f2d02fd9d9
-  data.tar.gz: 3b67abd203cd1619bc2de88fb4259437a994ec970ef58e81c937ca68efc0ebebc71588942942efa06e6dc56191af8935891c945d5241d87df3c5440787fa18be
+  metadata.gz: 82c0c748046529933359f27c5c46dc821f64f6b8b8bfee78b27b477155cf33f446f17ddc8b89b17eadda4afc1f643b588b6ecab88a64499dc4aa91afc38f3156
+  data.tar.gz: 52f9314a98ab708877b04832bd52aa5f7732c20999b597e8c4abe936d7fa285d49fabe9624e73a55b75c32d62dbf3a2b40e95701bd26462f671df8851fd3577c

data/README.md

@@ -4,16 +4,105 @@
   <img src="assets/logo.png" alt="btape logo" width="480">
 </p>
 
-`btape` is a small, VHS-inspired Ruby CLI that runs browser actions from a
-`.tape` file and records them as an animated GIF. Ferrum controls Chromium
-and captures PNG frames, and a pure-Ruby encoder produces the GIF. It
-does not require Playwright, Selenium, ffmpeg, or an external service.
+<p align="center">
+  <img src="assets/demo.gif" alt="btape recording a login flow into an animated GIF" width="720">
+</p>
+
+<p align="center">
+  <sub>Run a <code>.tape</code> file, get that GIF. This one is <code>examples/demo.tape</code>.</sub>
+</p>
+
+## What is btape
+
+A `.tape` file lists the browser actions you would otherwise click through by
+hand. `btape` performs them against a real browser and records what the page
+did as an animated GIF:
+
+```text
+Output demo.gif
+Viewport 1280x720
+
+Goto https://example.com
+Click "text=Login"
+Type "#email" "demo@example.com"
+Sleep 2s
+```
+
+It is a small, VHS-inspired Ruby CLI. Ferrum controls Chromium and captures
+PNG frames, and a pure-Ruby encoder produces the GIF. It does not require
+Playwright, Selenium, ffmpeg, or an external service.
 
 Tapes are written by hand, or asked of a language model running on the same
 machine: `btape generate` describes the language to LM Studio, Ollama or
 anything else speaking their API, and holds the answer to the parser before
 handing it over.
 
+## Demo
+
+The GIF above was recorded by btape itself, from `examples/demo.tape` driving
+`examples/demo_app.html` — a static page bundled with the repository, so the
+demo needs no other service running:
+
+```text
+Output demo.gif
+Viewport 1280x720
+
+Goto file:///app/examples/demo_app.html
+Sleep 500ms
+
+Click "text=Login"
+Sleep 300ms
+Type "#email" "demo@example.com"
+Type "#password" "password"
+Click "text=Sign in"
+Sleep 2s
+```
+
+`file:///app/…` is where the development container mounts the checkout, so
+`dip demo` records it as it stands. Outside the container, point `Goto` at
+your own copy of that file — or at any URL at all, which is the point.
+
+## Install
+
+```sh
+gem install btape
+```
+
+or, in a Gemfile:
+
+```ruby
+gem 'btape'
+```
+
+Chromium — or Chrome — must be installed and discoverable by Ferrum:
+`brew install --cask chromium` on macOS, `apt-get install chromium` on Debian
+or Ubuntu. A browser installed somewhere unusual is named by `BROWSER_PATH`,
+and one running on another machine by `--ws-url`; see
+[A browser running somewhere else](#a-browser-running-somewhere-else).
+
+## Quick start
+
+Write `demo.tape`:
+
+```text
+Output demo.gif
+Viewport 1280x720
+
+Goto https://example.com
+Sleep 1s
+```
+
+and run it:
+
+```sh
+btape demo.tape
+# Created /path/to/demo.gif
+```
+
+`Output` is where the GIF goes, resolved relative to the tape file. Point
+`Goto` at your own application and add `Click`, `Type` and `WaitFor` lines
+until the recording shows what you want it to. The whole language is below.
+
 ## Commands
 
 ```text
@@ -32,27 +121,53 @@ Screenshot [name]
 Sleep <number>ms|s
 ```
 
+| Command | What it does |
+| --- | --- |
+| `Output` | Where the GIF is written. Required, and read before the run wherever it appears |
+| `Viewport` | The size the page is rendered at, and so the size of the GIF before `Scale` |
+| `Set` | Configures the run rather than acting on the page; the names are in [Settings](#settings) |
+| `Goto` | Navigates the page, and puts the following commands back in the main frame |
+| `Click` | Clicks the first element the selector matches |
+| `Type` | Focuses the first element the selector matches and types the text into it |
+| `Press` | Presses a key by name — `Enter`, `Tab`, `Right` — once, or `count` times |
+| `Frame` | Points the following commands at an iframe; `Frame main` returns to the page |
+| `Evaluate` | Runs JavaScript in the current frame |
+| `WaitFor` | Polls until the selector matches something, then carries on |
+| `WaitForJS` | Polls until the JavaScript returns something truthy |
+| `Screenshot` | Captures one frame now, and with a name puts it at a predictable path too |
+| `Sleep` | Holds where it is for the duration, recording all the while |
+
 Arguments containing spaces must be quoted. Empty lines and lines beginning
 with `#` are ignored. `Output` is required; `Viewport` defaults to `1280x720`.
-Output paths are resolved relative to the tape file.
-
-```text
-Output demo.gif
-Viewport 1280x720
-Goto http://localhost:3000
-Click "text=Login"
-Type "#email" "demo@example.com"
-Sleep 1s
-```
-
-`Evaluate` runs JavaScript in the current frame, which is how a tape reaches
-an API the page exposes rather than clicking at it. `Frame` points the
-commands that follow at an iframe, and `Frame main` returns to the page;
-navigating returns to the page too, since the frame belonged to the page that
-was left. `WaitFor` and `WaitForJS` poll instead of guessing at a `Sleep`.
-
-`Screenshot` captures a frame there and then. With a name it also lands at a
-predictable path, for picking one particular frame out of a run.
+Output paths are resolved relative to the tape file. Selectors are CSS, or
+`text=Some text` to match an element by the text it shows. Durations are a
+number followed by `ms` or `s` — `500ms`, `1.5s`.
+
+`Evaluate` is how a tape reaches an API the page exposes rather than clicking
+at it. It runs in whatever frame is current, which is the page until a `Frame`
+says otherwise; navigating returns to the page too, since the frame belonged
+to the page that was left.
+
+`WaitFor` and `WaitForJS` poll instead of guessing at a `Sleep`. Both check
+every `WaitInterval`, and are satisfied only once `WaitStable` checks in a row
+have passed; a check that fails puts the count back to zero, so a page that
+reports itself ready before it has settled is caught by raising `WaitStable`
+above 1. A duration on the line is how long that one wait gets, and
+`WaitTimeout` is how long the ones without get. Neither raises for a check
+that failed — only running out of time does, against the line that was
+waiting. An expression that raises counts as not-yet-true rather than as an
+error, but the last thing it raised is named in the timeout, so an expression
+that could never be true still says why.
+
+`Screenshot` captures a frame there and then. It is what `Set CaptureMode
+manual` records with — one frame per page of a deck, rather than a few hundred
+near-identical ones — and a name makes that one frame findable afterwards, as
+`frame-NAME.png` under `--frames-dir` and as `result.named_frames['NAME']`
+from Ruby.
+
+`Sleep` is for holding a finished frame on screen long enough to be seen,
+which is a different job from waiting for the page: interval recording carries
+on throughout one, so a `Sleep` is what gives a GIF its pauses.
 
 ## Settings
 
@@ -76,15 +191,7 @@ can run in more than one place.
 | `WaitStable` | `1` | How many checks in a row must pass before a wait is satisfied |
 | `MaxFrames` | `600` | Stop rather than record a hung page until the disk fills |
 
-## Install and run
-
-Chromium must be installed and discoverable by Ferrum. Then:
-
-```sh
-bundle install
-bundle exec btape demo.tape
-bundle exec rake spec
-```
+## Command line
 
 ```text
 Usage: btape [options] SCRIPT.tape
@@ -100,6 +207,35 @@ Subcommands:
 
 `BTAPE_WS_URL` is used when neither `--ws-url` nor `--set WsUrl=` is given.
 
+## Advanced usage
+
+### A browser running somewhere else
+
+btape launches its own Chromium by default. Point it at one that is already
+running — a `browserless`/`chrome` container, say — and no browser needs to be
+in the image btape runs from:
+
+```sh
+btape --ws-url ws://chrome:3000 examples/thumbnails.tape
+```
+
+Each connection gets its own browser context, so concurrent runs against one
+shared browser do not see each other. The viewport is applied over the wire,
+since a browser that is already running cannot be told its window size at
+launch.
+
+`examples/thumbnails.tape` is the other shape of run: one frame per page of a
+deck, captured with `Set CaptureMode manual` against a remote browser.
+
+### Frames, not just the GIF
+
+Frames are normally written to a temporary directory and removed as the run
+unwinds. `--frames-dir` keeps them:
+
+```sh
+btape --frames-dir frames examples/thumbnails.tape
+```
+
 ### Fonts, and text that is not Latin
 
 Glyphs come from the fonts the browser can see, which is not necessarily the
@@ -166,31 +302,7 @@ WaitForJS "(() => { const c = document.createElement('canvas').getContext('2d');
 Tape files themselves are read as UTF-8 whatever the locale says, so a `Type`
 line or a `text=` selector can be written in any script.
 
-### A browser running somewhere else
-
-btape launches its own Chromium by default. Point it at one that is already
-running — a `browserless`/`chrome` container, say — and no browser needs to be
-in the image btape runs from:
-
-```sh
-btape --ws-url ws://chrome:3000 examples/thumbnails.tape
-```
-
-Each connection gets its own browser context, so concurrent runs against one
-shared browser do not see each other. The viewport is applied over the wire,
-since a browser that is already running cannot be told its window size at
-launch.
-
-### Frames, not just the GIF
-
-Frames are normally written to a temporary directory and removed as the run
-unwinds. `--frames-dir` keeps them:
-
-```sh
-btape --frames-dir frames examples/thumbnails.tape
-```
-
-## Writing a tape with a local model
+### Writing a tape with a local model
 
 `btape generate` describes the language to a model running on your own
 machine and asks it for a tape:
@@ -238,7 +350,7 @@ when told which line. What it cannot know is your markup, so a tape it wrote
 still names selectors that have to be checked against the page. Read it before
 you run it, the way you would read anything else generated for you.
 
-### A model that is not on this machine
+#### A model that is not on this machine
 
 `--llm-url` is the whole of the configuration, so a hosted endpoint speaking
 the same API works as well as a local one. Name the model rather than leaving
@@ -261,7 +373,7 @@ model keeps the description and the `--context` file on the machine that ran
 the command; a hosted one is handed both, and a context file is usually a page
 of your own markup rather than something you would have published.
 
-## From Ruby
+### From Ruby
 
 `Runner#run` returns a `Btape::Result`:
 
@@ -310,10 +422,19 @@ tape = generator.call('record the dashboard loading', context: page_markup)
 Btape::Runner.new.run(Btape::Parser.new.parse(tape), base_directory: '.', output: buffer)
 ```
 
-## Container development with dip or wip
+## Development
 
-The development image contains Ruby, Chromium and Latin fonts; tapes that
-record other scripts need fonts for them added to it.
+Working on btape itself, rather than using it, starts from a checkout:
+
+```sh
+bundle install
+bundle exec rake spec
+bundle exec rake rubocop
+bundle exec exe/btape examples/demo.tape
+```
+
+Or from the development image, which contains Ruby, Chromium and Latin fonts;
+tapes that record other scripts need fonts for them added to it:
 
 ```sh
 dip provision
@@ -325,11 +446,9 @@ wip dispatch demo
 wip dispatch btape examples/demo.tape
 ```
 
-`examples/demo.tape` drives a small static page bundled at
-`examples/demo_app.html`, so the demo is self-contained and needs no other
-service running. Edit the tape (or point `Goto` at a different URL) to record
-something else. `examples/thumbnails.tape` shows the other shape of run: one
-frame per page of a deck, against a browser running elsewhere.
+CI runs the specs and RuboCop across Ruby 3.2 to 4.0, and records
+`examples/demo.tape` against a real Chromium to check that a GIF still comes
+out the other end. [CONTRIBUTING.md](CONTRIBUTING.md) has the rest.
 
 ## Limitations
 
@@ -356,3 +475,8 @@ This project follows the [Code of Conduct](CODE_OF_CONDUCT.md).
 ## License
 
 [MIT](LICENSE)
+
+## Repository topics
+
+Suggested GitHub topics for this repository: `browser-automation`, `chromium`,
+`cli`, `ruby`, `developer-tools`, `screen-recording`, `gif`, `ferrum`, `vhs`.

data/lib/btape/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Btape
-  VERSION = '0.3.0'
+  VERSION = '0.4.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: btape
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - btape contributors