ruby_raider 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df32b6a642777030f39db11a96cc9a85a5f59fce1528e9d096f2acd5e6bca3f9
-  data.tar.gz: 49713a619c80897c37b68e91c0c3b5acff9917fe9d850cbfde2fa6827345914b
+  metadata.gz: 07307a2abf36b62e163df5530bb3666faa9ee1837623909e5242dce43086b8b1
+  data.tar.gz: 32388fc57a5acb2e497f68c654a750379a3c40841ac849321d2d083bb0019055
 SHA512:
-  metadata.gz: 02fea0f644525a60e0cbdf2fbac17194272480915cc57f486dade1c12f2ca6ecf64b021d120aaf25fa84a9bad085c5e1e958b1537e9f2e979361fbb0353aae65
-  data.tar.gz: 1da4cd4c6161a49663c9198f67847724edf1c7baa4c0988df86ea5c80361ad411af3ff83a0cdf9ed6e34a76d22208c782d44bd451e04c15d3d72bda582cb7186
+  metadata.gz: a6ec8338233eeba0dbe5bc400ff16ea0ec2fa3a3003464b6a9f7c230e7f7ee004f0db0ebd5f8c6ee8759f2192ddd83d5d5298025d40f829fc09e20c74a75647d
+  data.tar.gz: 9ce051d82e86b5f28e9d1fb9816f4069d11418ef1b12db53c1c7884a271d08225c45ac7d4f6a1b34545a64761e113140a7edbe7c98eba5c973f5e63b33d176de

data/.github/workflows/e2e_tests.yml

@@ -37,5 +37,8 @@ jobs:
       - name: Run command routing tests
         run: bundle exec rspec spec/commands/ --format documentation
 
+      - name: Run schedule tests
+        run: bundle exec rspec spec/utilities/schedules --tag ~slow --format documentation
+
       - name: Run menu tests
         run: bundle exec rspec spec/menus/ --format documentation

data/README.md

@@ -198,62 +198,61 @@ Example projects log in once and restore the saved session for examples tagged `
 - The state stays in git-ignored `.raider/auth/`.
 - Skeletons (`examples:false`) get `SessionState#reuse` to wire your own login.
 
-### Flows: run without assertions (web)
+### Scheduling tests
 
-A flow is a recorded chore with no checks, such as logging in and downloading a report. It is done when every step ran. Flows are RSpec files under `flows/`, so they use the same driver, locators, waiting, screenshots, video and trace as your tests.
-
-```
-raider flow init                     # adds flows/flow_helper.rb, flows/support/run.rb and .gitignore lines
-raider flow run timesheet            # runs flows/timesheet_flow.rb headless
-raider flow run timesheet --headed --retries 2 --input hours=7
-raider flow list [--json]            # each flow and its last result
-```
-
-```ruby
-# flows/timesheet_flow.rb
-require_relative 'flow_helper'
-
-RSpec.describe 'Fill the timesheet' do
-  it 'saves the hours' do
-    driver.navigate.to 'https://example.com/timesheet'
-    driver.find_element(label: 'Hours').send_keys(flow_input('hours', '8'))
-    driver.find_element(by_role('button', name: 'Save')).click
-  end
-end
-```
-
-- **Exit codes:** 0 completed, 1 a step failed, 2 setup failed (bundle, driver, missing helper), 3 the flow is already running. Each flow holds its own lock in `.raider/flows/`, and a second run exits 3 straight away.
-- **Results:** each run gets its own `flow-results/<name>/<UTC time>/` (report, failure screenshot, video and trace), and `.raider/flows/<name>/runs.jsonl` gains one line: `started_at`, `finished_at`, `status` (`completed`, `failed`, `setup_error`, `busy`), `failed_step`, `attempt`, `trigger`, `results_dir`. The last 20 result folders and 50 lines are kept. Flow runs never touch `raider-results/`, and test runs never touch `flow-results/`.
-- **Inputs:** `flow_input('name', 'default')` reads `--input name=value` (`RAIDER_INPUT_NAME`). Inputs show up in your shell history and process list, so keep secrets out of them.
-- **Secrets:** put them in `.raider/flows/env` as `KEY=value` lines (`#` comments, no interpolation). The file is loaded only when you own it and it has permissions 600 (`chmod 600 .raider/flows/env`); otherwise the run warns and goes on without it. Values are never written to the run log (they are replaced with `[secret]`), but your flow's own output and errors are printed as they are. On Windows there are no permission bits, so the folder's access rules protect the file: keep the project in your user folder.
-- **The same record every way:** `bundle exec rspec flows/timesheet_flow.rb` writes the same run log as `raider flow run`; `raider flow run` adds retries (whole flow, 30 s apart) and the exit codes. Set `RAIDER_FLOW_HEADED=1` to watch a plain rspec run (`headless: true` in `config/config.yml` still wins).
-- Projects made with 4.0 can add flows: `raider flow init` raises the Gemfile's `ruby_raider` pin to `~> 4.1`; run `bundle install` after it.
-
-### Scheduling flows
-
-Your computer's own scheduler runs the flow, so nothing needs to stay open. Scheduling never asks for sudo or admin rights.
+Your computer's own scheduler runs the project's tests: all of them, one tag, or a list of spec files. Nothing needs to stay open, and scheduling never asks for sudo or admin rights. `raider sc` is short for `raider schedule`.
 
 ```bash
-raider flow schedule timesheet --every weekday --at 17:30 --input hours=7 --notify
-raider flow schedule backup --every hour --at :15
-raider flow schedule report --every week --on fri --at 09:00 --retries 2
-raider flow unschedule timesheet
-raider flow schedules [--json]       # each schedule, its next run, last result and OS state
+raider schedule add nightly --every day --at 02:00 --notify
+raider schedule add smoke --every hour --at :15 --tag smoke --retries 1
+raider schedule add checkout spec/cart_spec.rb spec/checkout_spec.rb --every weekday --at 08:30 --show-browser
+raider schedule add weekly --every week --on fri --at 18:00 --project ~/code/my_tests
+raider schedule list [--json]        # each schedule, its next run, last result and OS state
+raider schedule run nightly          # run it now, the way the scheduler does
+raider schedule remove nightly
 ```
 
-- **Rules:** `--every hour|day|weekday|week`. `--at HH:MM` (24h, local time) is required for `day`, `weekday` and `week`; for `hour` use `--at :MM` (default `:00`). `--on mon|tue|wed|thu|fri|sat|sun` is required for `week` and refused otherwise. `--retries N` (0 to 3) and `--input name=value` are passed to `raider flow run`. Scheduling a flow again replaces its schedule.
-- **Schedulers:** macOS uses launchd (`~/Library/LaunchAgents/dev.rubyraider.flow.<hash>.<name>.plist`). Windows uses Task Scheduler (a task in the `\RubyRaider\` folder). Linux uses a systemd user timer in `~/.config/systemd/user`, or, when `systemctl --user` does not answer, one tagged line in your crontab. Times are local time (cron uses the system time zone).
-- **Missed runs:** launchd runs a run missed while the Mac slept once on wake. Task Scheduler runs it as soon as it can. systemd (`Persistent=true`) runs it once your user manager is back, at the next boot or login. cron skips it, and `raider flow schedules` says so.
-- **Logged in:** on macOS (a launchd agent in your GUI session) and Windows (a task that runs only while you are logged on) a run happens only while you are logged in.
-- **Linux:** systemd user timers stop when you log out unless lingering is on: `loginctl enable-linger $USER` (raider does not run it). A systemd schedule can only be removed from a session where `systemctl --user` works; until then `unschedule` refuses and keeps the entry.
-- **Per machine:** schedules live in `.raider/flows/schedules.yml`, which `raider flow init` git-ignores, so a fresh clone has none. schedules.yml is the source of truth, and the next run is worked out from the rule. Each OS entry is tied to the project's path: unschedule before you move the project.
-- **States:** `ok`, `missing from launchd` (or `Task Scheduler`, `systemd`, `cron`) when the OS entry is gone, `missing from schedules.yml` when the OS still runs a flow the file does not list, `Ruby not found: re-schedule`, `flow not found: unschedule` when `flows/<name>_flow.rb` was deleted or renamed, and `unknown (...)` when the scheduler could not be asked.
-- **Ruby:** the OS entry runs the absolute `ruby` and `bundle` paths captured when you scheduled, plus `GEM_HOME` and `GEM_PATH` on macOS and Linux. After a Ruby upgrade or move, `schedules` says `Ruby not found: re-schedule`: run `raider flow schedule` again.
-- **Logs:** on macOS and Linux the scheduler's output goes to `.raider/flows/<name>/scheduler.log`. Windows tasks run ruby.exe directly with your user environment and keep no scheduler.log; each run's result is in `runs.jsonl` as always.
-- **Notify:** `--notify` shows a desktop notification only when a run ends failed or could not start (not when it completed, was already running, or was stopped). macOS uses `osascript`, Linux `notify-send`, Windows a PowerShell toast. When a run could not start, the notification points at `.raider/flows/<name>/scheduler.log` for a scheduled run on macOS and Linux, and at the run output otherwise. A notification that can't be shown prints a warning and never changes the exit code. On Linux `notify-send` needs your desktop session bus: under cron, and in a systemd user session that has not imported it, it usually can't show, and only the warning lands in scheduler.log. `raider flow run --notify` does the same for a manual run.
-- **Secrets:** keep them in `.raider/flows/env`, never in `--input`: inputs are stored in plain text in the OS entry and in schedules.yml.
-- **Windows refusals:** Task Scheduler expands `%NAME%` with no way to escape it, so an input or path holding `%...%` is refused. An argument holding both `'` and one of `* ? [ {` is refused too, because ruby.exe would glob it.
-- **Tested on:** macOS (launchd) is tested against the real scheduler. Task Scheduler, systemd and cron are covered by unit tests with a fake scheduler only.
+- **Rules:** `--every hour|day|weekday|week`. `--at HH:MM` (24h, local time) is required for `day`, `weekday` and `week`; for `hour` use `--at :MM` (default `:00`). `--on mon|tue|wed|thu|fri|sat|sun` is required for `week` and refused otherwise. Names use 1 to 60 of `a-z`, `0-9` and `_`. Adding a name again replaces its schedule.
+- **What runs:** no files and no `--tag` runs all tests. `--tag TAG` runs one tag (letters, digits, `_`, `:` and `-`). Spec files are relative paths inside the project ending in `_spec.rb`, at most 200, and they can go before or after the options. `--tag` and files can't be used together.
+- **Your project's gem:** the scheduler runs `bundle exec raider schedule run` in your project, so `add` checks its `Gemfile.lock` first and refuses an older ruby_raider ("Scheduling needs ruby_raider X or later in this project: bundle update ruby_raider"), or a project with no `Gemfile.lock` yet (run `bundle install` first).
+- **`--project PATH`:** works from any folder. Put it after the subcommand (`raider schedule add nightly ... --project DIR`); before the subcommand Thor shows the help instead.
+- **Per machine:** schedules live in `.raider/schedules/schedules.yml`, which `add` git-ignores (it holds machine paths; projects made with 4.2 have the line already), so a fresh clone has none. The OS entry holds only the schedule's name: `raider schedule run NAME --project DIR --trigger schedule`. The selection, retries, notify and show-the-browser setting are read from schedules.yml at each run, which checks every entry again before anything starts.
+- **Show the browser:** scheduled runs are hidden (`HEADLESS=true`) unless you add `--show-browser`. It shows the browser whatever `headless` says in `config/config.yml`, and no driver change is needed: the runtime handles it (`RAIDER_SHOW_BROWSER=1` drops `--headless`). Neither config.yml nor `helpers/driver_helper.rb` is written.
+
+| Project Headless (config.yml) | Show the browser off | Show the browser on |
+|---|---|---|
+| off / absent | `HEADLESS=true`: hidden | `RAIDER_SHOW_BROWSER=1`, `HEADLESS` removed: visible |
+| on | `HEADLESS=true`: hidden | `RAIDER_SHOW_BROWSER=1`: visible (the runtime drops `--headless`) |
+
+- **Where a browser can show:** on macOS while you are logged in (a launchd agent runs in your GUI session). On Windows the task runs in your session while you are logged on; a visible browser there is not verified yet. On Linux `--show-browser` is refused ("Show the browser isn't available for scheduled runs on Linux"): systemd user units and cron have no display. A project made before 4.0 is refused too ("Show the browser needs a project made with Ruby Raider 4.0 or later").
+- **Retries:** `--retries N` (0 to 3) re-runs each failed test up to N times inside the same run, with rspec-retry (`RETRY_COUNT` is N + 1). From 4.2 the runtime gives a retried test a fresh browser. Before 4.2, a retry in a generated project failed with a refused connection, because the driver was already quit. The fix is in the gem (`ruby_raider/runtime/rspec`), so it also applies to manual runs such as `RETRY_COUNT=2 bundle exec rspec`; `bundle update ruby_raider` brings it to existing projects. A stop doesn't cut rspec-retry's tries short: the test running when you stop may still get its remaining tries before the run ends.
+- **Results:** a run is a normal `bundle exec rspec`, so its report goes to `raider-results/` and shows on the Dashboard. Each run also adds one line to `.raider/schedules/<name>/runs.jsonl` (`status` `passed`, `failed`, `setup_error` or `busy`, the counts and the trigger; the last 50 lines are kept), and the last report is copied to `.raider/schedules/<name>/last/` (run.json and index.html, plus the attachments when they come to 50 MB or less).
+- **Exit codes:** `raider schedule run` exits 0 passed, 1 failed, 2 could not start or refused, 3 another run was going (another `raider schedule run` in the project, or any run that holds `.raider/schedules/running.json`). Only one scheduled run per project goes at a time, and a busy run leaves `raider-results/` alone. Other commands exit 0, or 2 with one line on stderr. Thor's own usage errors (a missing NAME, a bad `--retries`) exit 1 with Thor's text.
+- **Notify:** `--notify` shows a desktop notification only when a run failed or could not start (not when it passed, was busy or was stopped). The title is "Ruby Raider: <name> failed"; the body says how many tests failed, or why the run could not start. macOS uses `osascript`, Linux `notify-send`, Windows a PowerShell toast. A notification that can't be shown prints a warning and never changes the exit code. On Linux `notify-send` needs your desktop session bus, so under cron, and in a systemd user session that has not imported it, it usually can't show.
+- **Schedulers:** macOS uses launchd (`~/Library/LaunchAgents/dev.rubyraider.schedule.<hash>.<name>.plist`). Windows uses Task Scheduler (a task in the `\RubyRaider\` folder). Linux uses a systemd user timer in `~/.config/systemd/user`, or, when `systemctl --user` does not answer, one tagged line in your crontab. Times are local time (cron uses the system time zone).
+- **Missed runs:** launchd runs a run missed while the Mac slept once on wake. Task Scheduler runs it as soon as it can. systemd (`Persistent=true`) runs it once your user manager is back, at the next boot or login. cron skips it, and `raider schedule list` says so.
+- **Logged in:** on macOS and Windows a run happens only while you are logged in. On Linux, systemd user timers stop when you log out unless lingering is on: `loginctl enable-linger $USER` (raider does not run it). A systemd schedule can only be removed from a session where `systemctl --user` works; until then `remove` refuses and keeps the entry.
+- **States:** `ok`, `missing from launchd` (or `Task Scheduler`, `systemd`, `cron`) when the OS entry is gone, `missing from schedules.yml` when the OS still runs a schedule the file does not list, `Ruby not found: re-schedule`, `test file not found: <file>` when a listed spec file was deleted or renamed, and `unknown (...)` when the scheduler could not be asked.
+- **Ruby:** the OS entry runs the absolute `ruby` and `bundle` paths captured when you added it, plus `GEM_HOME` and `GEM_PATH` on macOS and Linux. After a Ruby upgrade or move, run `raider schedule add` again.
+- **Logs:** on macOS and Linux the scheduler's output goes to `.raider/schedules/<name>/scheduler.log`, moved to `scheduler.log.1` at the start of a scheduled run once it is over 1 MB. Windows tasks keep no scheduler.log; each run's result is in `runs.jsonl` as always.
+- **Windows refusals:** Task Scheduler and ruby.exe would expand `%...%`, `*`, `?`, `[` or `{`, so a spec file or path holding them is refused: rename the file or use a tag.
+- **Moving the project:** each OS entry is tied to the project's path (`<hash>` is made from it). Run `raider schedule remove` before you move the project. Entries made before a move keep the old path's id, so `list` in the new place can't find them. Remove them by hand; their names start with `dev.rubyraider.schedule.`:
+  - macOS: `launchctl bootout gui/$UID/<label>`, then delete `~/Library/LaunchAgents/<label>.plist`.
+  - Windows: `schtasks /Delete /TN \RubyRaider\<id> /F`.
+  - Linux (systemd): `systemctl --user disable --now <id>.timer`, delete `<id>.timer` and `<id>.service` from `~/.config/systemd/user`, then `systemctl --user daemon-reload`.
+  - Linux (cron): `crontab -e` and delete the `# raider-schedule <id>` line and the line under it.
+- **Tested on:** macOS (launchd) is tested against the real scheduler: adding, a run started by launchd hidden and shown with Headless on, a failed run with a notification, a busy run, and removing. Task Scheduler, systemd and cron are covered by unit tests with a fake scheduler only.
+
+### Upgrading from 4.1
+
+- **Old schedules are removed automatically.** Schedules made with Ruby Raider 4.1 can't run in 4.2. They are removed the first time any `raider schedule` command runs in the project (such as `raider schedule list`), or the next time one of them fires. One line says which were removed.
+- **Add them again** with `raider schedule add`.
+- **Leftover folders:** `flows/`, `flow-results/` and `.raider/flows/` (it holds old secrets in `env`) are left alone. Delete them only after the line saying the old schedules were removed has appeared (run any `raider schedule` command, such as `raider schedule list`): the cleanup looks for `.raider/flows/`, and the old entries write their logs there.
+- **A project moved after scheduling** can't be cleaned automatically: its entries are tied to the old path. Remove them by hand; their names start with `dev.rubyraider.flow.`:
+  - macOS: find them with `ls ~/Library/LaunchAgents | grep dev.rubyraider.flow.`, run `launchctl bootout gui/$(id -u)/<label>`, then delete `~/Library/LaunchAgents/<label>.plist` (`<label>` is `dev.rubyraider.flow.<hash>.<name>`).
+  - Windows: find them with `schtasks /Query /FO CSV | findstr dev.rubyraider.flow.`, then `schtasks /Delete /TN "\RubyRaider\<id>" /F`.
+  - Linux (systemd): find them with `ls ~/.config/systemd/user | grep dev.rubyraider.flow.` (or `$XDG_CONFIG_HOME/systemd/user` when it is set), run `systemctl --user disable --now <id>.timer`, delete `<id>.timer` and `<id>.service` from `~/.config/systemd/user`, then `systemctl --user daemon-reload`.
+  - Linux (cron): find them with `crontab -l | grep -A1 '# raider-flow '`, then `crontab -e` and delete each `# raider-flow <id>` line and the line under it.
 
 ### Also included
 
@@ -327,12 +326,12 @@ The skeleton keeps the helpers, config, CI and README, and its empty suite passe
 raider new [PROJECT_NAME]       # Create a new framework project
 raider generate                 # Access scaffolding commands
 raider utility                  # Access utility commands
-raider flow                     # Run flows: init, run, list, schedule
+raider schedule                 # Schedule the tests: add, list, remove, run
 raider version                  # Show current version
 raider help [COMMAND]           # Describe available commands
 ```
 
-Shortcuts: `n` (new), `g` (generate), `u` (utility), `f` (flow), `v` (version)
+Shortcuts: `n` (new), `g` (generate), `u` (utility), `sc` (schedule), `v` (version)
 
 ### Scaffolding Commands
 

data/RELEASE.md

@@ -2,7 +2,20 @@
 
 ## Release Notes
 
-### 4.1.0 (unreleased)
+### 4.2.0
+
+- `raider schedule add NAME [SPEC_FILE ...] --every hour|day|weekday|week [--at HH:MM | :MM] [--on mon..sun] [--tag TAG] [--show-browser] [--retries 0..3] [--notify]` runs the project's tests with the computer's own scheduler (launchd, Task Scheduler, a systemd user timer or cron, as in 4.1). `raider schedule list [--json]`, `remove NAME` and `run NAME [--trigger manual|schedule]` complete it; every command takes `--project PATH`. `raider sc` is short for `raider schedule`.
+- A schedule runs all tests, one tag (`--tag`), or up to 200 spec files given by path (relative, inside the project, ending `_spec.rb`); a tag and files can't be combined. Schedules live in `.raider/schedules/schedules.yml`, which `add` git-ignores; projects made with `raider new` 4.2 have the `.raider/schedules/` line from the start. The OS entry holds only the schedule's name: the selection and options are read from the yml, and checked again, at each run.
+- `--show-browser` shows the browser in a scheduled run whatever the project's `headless` setting says, with no project file changed: when `RAIDER_SHOW_BROWSER=1`, the runtime drops `--headless` from the Chrome, Edge and Firefox options. Refused for projects made before 4.0 and on Linux; on macOS the user must be logged in, and Windows is unverified.
+- `--retries N` re-runs each failed test up to N times inside the same run with rspec-retry (`RETRY_COUNT = N + 1`). A stop doesn't cut the tries of the test in flight short.
+- `raider schedule add` refuses a project whose `Gemfile.lock` resolves an older ruby_raider, or that has no `Gemfile.lock` yet, so a schedule never fires into a bundle without `raider schedule`.
+- Retried tests get a fresh browser. Before this, a retry in a generated 4.x project failed with a refused connection because the driver was already quit. The fix is in the runtime (`ruby_raider/runtime/rspec`), so it reaches every 4.x project on `bundle update ruby_raider` and also applies to manual `RETRY_COUNT=2 bundle exec rspec` runs.
+- Scheduled results go to `raider-results/` (the Dashboard), one line per run in `.raider/schedules/<name>/runs.jsonl` (last 50 kept), and a copy of the last report in `.raider/schedules/<name>/last/`. `scheduler.log` is rotated once over 1 MB.
+- `--notify` shows a desktop notification ("Ruby Raider: <name> failed") only when a run failed or could not start, with 4.1's channels.
+- `raider schedule run` exits 0 passed, 1 failed, 2 could not start or refused, 3 another run was going: another `raider schedule run` in the project, or any run that holds `.raider/schedules/running.json` (a busy run leaves `raider-results/` alone).
+- `raider schedule` runs your tests on a schedule. The 4.1 recording-without-checks commands are gone, and their schedules are removed automatically: the first `raider schedule` command in a project, or the old entry's next firing, removes them and prints one line. The folders they used are left for you to delete (see Upgrading from 4.1 in the README).
+
+### 4.1.0 (2026-11-10)
 
 - Flows: recordings without assertions that run on their own. `raider flow init` adds `flows/flow_helper.rb` and `flows/support/run.rb` to a Selenium web project made with 4.0 or later (and raises a `~> 4.0` Gemfile pin to `~> 4.1`); mobile and 3.x projects are refused with exit 2.
 - `raider flow run NAME` runs `flows/NAME_flow.rb` headless with `bundle exec rspec`, exiting 0 completed, 1 a step failed, 2 setup failed, 3 already running. `--headed`, `--retries N` (0 to 3, whole flow, 30 s apart), `--input name=value` (read with `flow_input`) and `--trigger manual|schedule|desktop`. `--project PATH` works from any folder.

data/lib/commands/schedule_commands.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative '../utilities/schedules/legacy'
+require_relative '../utilities/schedules/scheduler'
+require_relative '../utilities/schedules/run_wrapper'
+
+# raider schedule: runs the project's tests (all, one tag or listed spec files) with the OS scheduler.
+# Spec files are positional, never an array option, so they mix with the options in any order.
+# Every command first removes the project's 4.1 schedules (Legacy), which never changes its exit code or stdout.
+class ScheduleCommands < Thor
+  def self.exit_on_failure? = true
+
+  class_option :project, type: :string, desc: 'The project folder (default: the current folder)'
+
+  desc 'add NAME [SPEC_FILE ...]', 'Schedules the tests (all, --tag or the spec files), or replaces the schedule NAME'
+  option :every, type: :string, desc: 'hour, day, weekday or week'
+  option :at, type: :string, desc: 'HH:MM (24h, local time); for every hour :MM'
+  option :on, type: :string, desc: 'mon to sun, for every week'
+  option :tag, type: :string, desc: 'Run only the tests with this tag'
+  option :show_browser, type: :boolean, desc: 'Show the browser, whatever the Headless setting'
+  option :retries, type: :numeric, default: 0, desc: 'Re-run each failed test up to N times (0-3)'
+  option :notify, type: :boolean, desc: 'Show a desktop notification when a scheduled run fails'
+
+  def add(name, *files)
+    scheduler.add(name, every: options[:every], files: files, tag: options[:tag], at: options[:at], on: options[:on],
+                        retries: options[:retries], notify: options[:notify] || false,
+                        show_browser: options[:show_browser] || false)
+  rescue RubyRaider::Schedules::Error => e
+    stop(e)
+  end
+
+  desc 'list', 'Lists the schedules with their next run and last result'
+  option :json, type: :boolean, desc: 'Print JSON for the desktop app'
+
+  def list
+    project = new_project
+    notice = cleanup(project)
+    RubyRaider::Schedules::Scheduler.new(project).list(json: options[:json] || false, notice: notice)
+  rescue RubyRaider::Schedules::Error => e
+    stop(e)
+  end
+
+  desc 'remove NAME', 'Removes the schedule NAME from the OS scheduler and schedules.yml'
+
+  def remove(name)
+    scheduler.remove(name)
+  rescue RubyRaider::Schedules::Error => e
+    stop(e)
+  end
+
+  # `run` is a Thor reserved word, so the method has another name
+  desc 'run NAME', 'Runs the schedule NAME now: exit 0 passed, 1 failed, 2 setup error, 3 busy'
+  option :trigger, type: :string, default: 'manual', desc: 'manual or schedule (what the OS entry passes)'
+
+  def run_schedule(name)
+    exit(RubyRaider::Schedules::RunWrapper.new(cleaned_project).run(name, trigger: options[:trigger]))
+  rescue RubyRaider::Schedules::Error => e
+    stop(e)
+  end
+
+  map 'run' => :run_schedule
+
+  no_commands do
+    def new_project = RubyRaider::Schedules::Project.new(options[:project] || Dir.pwd)
+
+    # The project, once its 4.1 schedules are cleaned up
+    def cleaned_project = new_project.tap { |project| cleanup(project) }
+
+    # Removes the project's 4.1 schedules; the notice (on stderr already), nil when there was nothing to remove.
+    # Without the 4.1 folder (Legacy.folder?) there is none, so that costs one lstat.
+    def cleanup(project)
+      RubyRaider::Schedules::Legacy.new(project).cleanup if RubyRaider::Schedules::Legacy.folder?(project)
+    end
+
+    def scheduler = RubyRaider::Schedules::Scheduler.new(cleaned_project)
+
+    # One stderr line, whatever the message holds (a --project path can carry a newline)
+    def stop(error)
+      warn(RubyRaider::Schedules.printable(error.message))
+      exit(error.exit_code)
+    end
+  end
+end

data/lib/generators/templates/common/git_ignore.tt

@@ -1,5 +1,6 @@
 raider-results
 spec/examples.txt
+.raider/schedules/
 <%- if web? -%>
 .raider/auth/
 <%- end -%>

data/lib/ruby_raider/runtime/retry_reset.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Raider
+  # rspec-retry runs a retried example again in the same example group instance. The project's after
+  # hook has quit the driver by then, and its driver_helper memoises it in @driver, so the retry would
+  # reuse a dead session. Before each retry this clears @driver: the next `driver` call starts a fresh
+  # one. Nothing is quit here.
+  #
+  # Installed from a before(:suite) hook, so it sees the final configuration whatever the require
+  # order. Without rspec-retry it does nothing. A retry_callback the project set is kept as it is,
+  # and then the project owns the reset.
+  #
+  # It relies on the after hook quitting the driver. A project whose after hook does not quit it leaves
+  # one browser open per retry (the cleared @driver is never quit); such a project should set its own
+  # retry_callback that quits and clears the driver.
+  module RetryReset
+    CALLBACK = proc { |_example| @driver = nil }
+
+    module_function
+
+    # True when the callback was set
+    def install(config = ::RSpec.configuration)
+      return false unless config.respond_to?(:retry_callback=)
+      return false if config.retry_callback
+
+      config.retry_callback = CALLBACK
+      true
+    end
+  end
+end
+
+::RSpec.configure { |config| config.before(:suite) { Raider::RetryReset.install } } if defined?(::RSpec::Core)

data/lib/ruby_raider/runtime/rspec.rb

@@ -7,6 +7,7 @@ require_relative 'matchers/element'
 require_relative 'matchers/page'
 require_relative 'matchers/presence'
 require_relative 'matchers/retrying_block'
+require_relative 'retry_reset'
 
 module Raider
   # Web-first RSpec matchers that retry until the page settles.

data/lib/ruby_raider/runtime/show_browser.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Raider
+  # Show the browser whatever the project's headless setting says. A scheduled or desktop run sets
+  # RAIDER_SHOW_BROWSER=1; the project's driver_helper still adds --headless, and the filter prepended
+  # here drops it. config.yml and driver_helper.rb are never written. Unset, nothing is prepended.
+  module ShowBrowser
+    ENV_KEY = 'RAIDER_SHOW_BROWSER'
+    OPTIONS = %w[Chrome Edge Firefox].map { |browser| "Selenium::WebDriver::#{browser}::Options" }.freeze
+    SWITCHES = %w[--headless -headless].freeze
+    PREFIX = '--headless='
+    ARGS_KEYS = [:args, 'args'].freeze
+
+    module_function
+
+    def headless?(arg) = arg.is_a?(String) && (SWITCHES.include?(arg) || arg.start_with?(PREFIX))
+
+    def without_headless(args) = args.is_a?(Array) ? args.reject { |arg| headless?(arg) } : args
+
+    # The Options classes the filter is on; empty unless the env value is exactly '1'
+    def install(env = ENV)
+      return [] unless env[ENV_KEY] == '1'
+
+      OPTIONS.filter_map do |name|
+        next unless Object.const_defined?(name)
+
+        klass = Object.const_get(name)
+        klass.prepend(Filter) unless klass.include?(Filter)
+        klass
+      end
+    end
+
+    # Drops the headless switches from args: given to new, from add_argument and from args=
+    # :reek:ModuleInitialize -- prepended to the Options classes: its initialize wraps theirs
+    module Filter
+      def initialize(**opts)
+        ARGS_KEYS.each { |key| opts[key] = ShowBrowser.without_headless(opts[key]) if opts.key?(key) }
+        super
+      end
+
+      # The args, as Selenium's own add_argument returns them, also when the switch is dropped
+      def add_argument(arg)
+        return options[:args] if ShowBrowser.headless?(arg)
+
+        super
+      end
+
+      def args=(value)
+        super(ShowBrowser.without_headless(value))
+      end
+    end
+  end
+end

data/lib/ruby_raider/runtime.rb

@@ -14,7 +14,9 @@ require_relative 'runtime/observer'
 require_relative 'runtime/actionability'
 require_relative 'runtime/strict'
 require_relative 'runtime/actionable'
+require_relative 'runtime/show_browser'
 
 Raider::Finders.check_api
 Raider::Finders.install
 Raider::Finders.guard
+Raider::ShowBrowser.install

data/lib/ruby_raider.rb

@@ -5,23 +5,38 @@ require 'thor'
 # Lazy-load top-level command classes to reduce CLI startup time.
 autoload :ScaffoldingCommands, File.expand_path('commands/scaffolding_commands', __dir__)
 autoload :UtilityCommands, File.expand_path('commands/utility_commands', __dir__)
-autoload :FlowCommands, File.expand_path('commands/flow_commands', __dir__)
+autoload :ScheduleCommands, File.expand_path('commands/schedule_commands', __dir__)
 
 module RubyRaider
   class Raider < Thor
     def self.exit_on_failure? = true
 
-    # Thor runs a regex on every argument before any command, so invalid UTF-8 would crash it with a
-    # backtrace; a flow command says which argument instead and exits 2 like its other refusals
+    # The commands whose arguments are checked for valid UTF-8 before Thor sees them
+    GUARDED = %w[schedule sc].freeze
+    # What a Ruby Raider 4.1 OS entry runs (`raider flow run ...`): a hidden stub, not a Thor command
+    LEGACY = %w[flow f].freeze
+
+    # The 4.1 stub goes first, whatever its argv holds. Thor runs a regex on every argument before any
+    # command, so invalid UTF-8 would crash it with a backtrace; a schedule command says which argument
+    # instead and exits 2 like its other refusals
     def self.start(given_args = ARGV, config = {})
+      exit(legacy_stub(given_args)) if LEGACY.include?(given_args.first)
       bad = given_args.find { |arg| arg.is_a?(String) && !arg.valid_encoding? }
-      if bad && %w[flow f].include?(given_args.first)
+      if bad && GUARDED.include?(given_args.first)
         warn("Invalid argument #{bad.inspect}: use valid UTF-8")
         exit(2)
       end
       super
     end
 
+    # Removes the project's 4.1 schedules and says why the command is gone; always 2
+    def self.legacy_stub(given_args)
+      require_relative 'utilities/schedules/legacy_stub'
+      Schedules::LegacyStub.run(given_args.drop(1))
+    rescue StandardError, ScriptError
+      2
+    end
+
     no_tasks do
       def current_version = File.read(File.expand_path('version', __dir__)).strip
     end
@@ -63,9 +78,9 @@ module RubyRaider
     subcommand 'utility', UtilityCommands
     map 'u' => 'utility'
 
-    desc 'flow', 'Runs flows: recordings without assertions (init, run, list, schedule)'
-    subcommand 'flow', FlowCommands
-    map 'f' => 'flow'
+    desc 'schedule', 'Runs the tests on a schedule with the OS scheduler (add, list, remove, run)'
+    subcommand 'schedule', ScheduleCommands
+    map 'sc' => 'schedule'
 
     no_tasks do
       # -p values arrive as strings; examples must be true or false, in any case

data/lib/utilities/schedules/adapter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+require_relative 'base'
+require_relative 'os/command_runner'
+require_relative 'os/launchd'
+require_relative 'os/task_scheduler'
+require_relative 'os/linux'
+
+module RubyRaider
+  module Schedules
+    # The OS scheduler for this machine, for schedules of the kind; only Linux asks the system (is the user's systemd there?)
+    def self.adapter(kind:, runner: Os::CommandRunner.new, host_os: RbConfig::CONFIG['host_os'])
+      case host_os
+      when /darwin/ then Os::Launchd.new(kind: kind, runner: runner)
+      when /mswin|mingw|cygwin/ then Os::TaskScheduler.new(kind: kind, runner: runner)
+      when /linux/ then Os::Linux.pick(runner, kind: kind)
+      else raise Error, kind.unsupported(host_os)
+      end
+    end
+  end
+end

data/lib/utilities/schedules/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyRaider
+  # The OS scheduler (launchd, Task Scheduler, systemd, cron) shared by test schedules and the 4.1 ones
+  # the cleanup removes. What differs between them is a Kind.
+  module Schedules
+    NAME = /\A[a-z0-9_]{1,60}\z/
+    # Schedule::DAYS order, as every adapter counts it
+    DAYS = %w[mon tue wed thu fri sat sun].freeze
+
+    def self.valid_name?(name) = NAME.match?(name.to_s)
+
+    # Text from a log or a command, safe to print: it can't move the cursor or forge lines, and bytes that
+    # are not valid in its encoding become ? too (a regexp would raise on them)
+    def self.printable(text) = text.to_s.scrub('?').gsub(/[[:cntrl:]]/, '?')
+
+    # A problem that stops a schedule command; exit_code follows `raider schedule run` (2 = setup failed).
+    class Error < StandardError
+      attr_reader :exit_code
+
+      def initialize(message, exit_code: 2)
+        super(message)
+        @exit_code = exit_code
+      end
+    end
+  end
+end

data/lib/utilities/schedules/kind.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RubyRaider
+  module Schedules
+    # What kind of schedule an OS entry belongs to: the words that name it in each scheduler (os_id prefix,
+    # cron tag, descriptions), the command it runs, where its files live and which names it takes.
+    # Adapters get one, so an entry of one kind is never read or removed as another.
+    # :reek:TooManyInstanceVariables { max_instance_variables: 9 } -- the words, folder and reserved names of one kind
+    class Kind
+      attr_reader :command, :os_id_prefix, :os_id_pattern, :dir, :noun, :plural, :remove_command, :stranded_hint, :reserved
+
+      # command is the raider subcommand (`raider <command> run NAME`); it also names the os_id prefix and tags.
+      # stranded_hint: what to run for a stranded timer, when it is not `<remove_command> NAME`
+      def initialize(command:, dir:, noun:, plural:, remove_command:, stranded_hint: nil, reserved: [])
+        @command = command.dup.freeze
+        @os_id_prefix = "dev.rubyraider.#{command}".freeze
+        @os_id_pattern = /\A#{Regexp.escape(@os_id_prefix)}\.[0-9a-f]{10}\.([a-z0-9_]{1,60})\z/
+        @dir = dir.dup.freeze
+        @noun = noun.dup.freeze
+        @plural = plural.dup.freeze
+        @remove_command = remove_command.dup.freeze
+        @stranded_hint = stranded_hint&.dup&.freeze
+        @reserved = reserved.map { |word| word.dup.freeze }.freeze
+        freeze
+      end
+
+      def valid_name?(name) = Schedules.valid_name?(name) && !reserved.include?(name.to_s)
+
+      # The name in an os_id of this kind, nil when it is not one
+      def name_in(os_id)
+        # Text from the OS (file names, schtasks, crontab) may not be valid UTF-8; a regexp would raise on it
+        return nil unless os_id.is_a?(String) && os_id.valid_encoding?
+
+        name = os_id_pattern.match(os_id)&.[](1)
+        name if name && valid_name?(name)
+      end
+
+      # An os_id of this kind that starts with prefix (one project's: "<os_id_prefix>.<hash10>.")
+      def listed?(os_id, prefix) = !name_in(os_id).nil? && os_id.to_s.start_with?(prefix)
+
+      def cron_tag = "# raider-#{command} "
+
+      # The command line under a cron tag runs `raider <command> run <name> --project ... --trigger schedule`
+      def our_command?(text, name) = text.include?(" exec raider #{command} run #{name} --project ") && text.include?(' --trigger schedule')
+
+      def task_description(name, rule) = "Ruby Raider #{command} #{name} (#{rule})"
+
+      def task_file_prefix = "raider-#{command}-task"
+
+      def service_description(name) = "raider #{command} #{name}"
+
+      def timer_description(name) = "raider #{command} #{name} schedule"
+
+      def not_ours = "not a #{noun}"
+
+      def stranded(name) = "This schedule is a systemd timer; run #{stranded_hint || "#{remove_command} #{name}"} from a session where systemctl --user works"
+
+      def unsupported(host_os) = "Scheduling #{plural} is not supported on #{host_os}"
+
+      # The schedules Ruby Raider 4.1 made (`raider flow schedule`), only ever removed now, by the cleanup every
+      # `raider schedule` command runs first (Legacy). The words the user reads never say flow; the command
+      # (os_id prefix, cron tag, the line under it) is what 4.1 wrote.
+      # remove_command is never printed for it: stranded_hint overrides it in stranded (list takes no name).
+      FLOW_LEGACY = new(command: 'flow', dir: '.raider/flows', noun: '4.1 schedule', plural: '4.1 schedules',
+                        remove_command: 'raider schedule list', stranded_hint: 'raider schedule list', reserved: %w[env])
+
+      # The schedules of `raider schedule`: the project's tests, all, one tag or listed spec files
+      TESTS = new(command: 'schedule', dir: '.raider/schedules', noun: 'test schedule', plural: 'tests',
+                  remove_command: 'raider schedule remove')
+    end
+  end
+end