ruby_raider 4.0.1 → 4.1.0

data/sig/utilities/flows/schedule_store.rbs

@@ -0,0 +1,34 @@
+module RubyRaider
+  module Flows
+    class ScheduleStore
+      DIR: String
+      FILE: String
+      NOFOLLOW: Integer
+      NONBLOCK: Integer
+
+      class Removed
+        attr_reader name: String
+        attr_reader os_id: String
+
+        def initialize: (String name, String os_id) -> void
+      end
+
+      def initialize: (Project project) -> void
+      def all: () -> Array[Schedule]
+      def find: (String name) -> Schedule?
+      def save: (Schedule schedule) -> Schedule
+      def writable!: () -> nil
+      def delete: (String name) -> (Schedule | Removed)?
+
+      private
+
+      def from_entry: (untyped entry) -> Schedule?
+      def named?: (untyped entry, String name) -> bool
+      def read_entries: () -> Array[untyped]?
+      def writable_entries: () -> Array[untyped]
+      def read_text: () -> (String | false)?
+      def write: (Array[untyped] entries) -> void
+      def private_dir: () -> String
+    end
+  end
+end

data/sig/utilities/flows/scheduler.rbs

@@ -0,0 +1,42 @@
+module RubyRaider
+  module Flows
+    class Scheduler
+      NOT_SET_UP: String
+      RUBY_NOT_FOUND: String
+      FLOW_NOT_FOUND: String
+      LAST: Array[String]
+      TIME: String
+
+      type row = { json: Hash[String, untyped], text: String }
+
+      @project: Project
+      @adapter: untyped
+      @store: ScheduleStore
+      @out: IO | StringIO
+      @err: IO | StringIO
+      @now: ^() -> Time
+
+      def self.adapter: (?runner: Os::CommandRunner, ?host_os: String) -> (Os::Launchd | Os::TaskScheduler | Os::Linux)
+
+      def initialize: (Project project, ?adapter: untyped, ?store: ScheduleStore, ?out: IO | StringIO, ?err: IO | StringIO, ?now: ^() -> Time) -> void
+      def schedule: (String name, every: String?, ?at: String?, ?on: String?, ?retries: untyped, ?inputs: Array[String], ?notify: bool) -> void
+      def unschedule: (String name) -> void
+      def schedules: (?json: bool) -> void
+
+      private
+
+      def adapter: () -> untyped
+      def save: (Schedule schedule) -> Schedule
+      def delete: (String name, String label) -> (Schedule | ScheduleStore::Removed)?
+      def flow_dir: (String name) -> void
+      def private_dir: (String relative) -> void
+      def row: (Schedule schedule, Time now) -> row
+      def unlisted_rows: (Array[String] listed) -> Array[row]
+      def present?: (String os_id) -> bool
+      def os_state: (Schedule schedule) -> String
+      def rule: (Schedule schedule) -> String
+      def last_run: (String name) -> Hash[String, untyped]?
+      def line: (String name, String rule, String next_run, Hash[String, untyped]? last, String state) -> String
+    end
+  end
+end

data/spec/commands/flow_commands_spec.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'tmpdir'
+require_relative '../../lib/ruby_raider'
+
+RSpec.describe FlowCommands do
+  let(:raider_bin) { File.expand_path('../../bin/raider', __dir__) }
+
+  def run_raider(*args)
+    Open3.capture3(RbConfig.ruby, raider_bin, *args)
+  end
+
+  it 'lists init, run and list in raider flow help' do
+    out, _err, status = run_raider('flow', 'help')
+
+    expect(status.exitstatus).to eq(0)
+    expect(out).to include('flow init', 'flow run NAME', 'flow list')
+  end
+
+  it 'maps raider f to the flow commands' do
+    out, _err, status = run_raider('f', 'help')
+
+    expect(status.exitstatus).to eq(0)
+    expect(out).to include('flow run NAME')
+  end
+
+  it 'is listed in raider help' do
+    out, = run_raider('help')
+
+    expect(out).to include('raider flow')
+  end
+
+  describe 'init' do
+    it 'sets up flows in the --project folder from any working directory' do
+      Dir.mktmpdir('flow-init') do |dir|
+        File.write(File.join(dir, 'Gemfile'), "gem 'ruby_raider', '~> 4.0'\ngem 'selenium-webdriver'\n")
+        FileUtils.mkdir_p(File.join(dir, 'helpers'))
+        File.write(File.join(dir, 'helpers/driver_helper.rb'), "require 'ruby_raider/runtime'\n")
+
+        out, _err, status = run_raider('flow', 'init', '--project', dir)
+
+        expect(status.exitstatus).to eq(0)
+        expect(out).to include('Created flows/flow_helper.rb', 'Run bundle install')
+      end
+    end
+
+    it 'exits 2 for a project that cannot hold flows' do
+      Dir.mktmpdir('flow-init') do |dir|
+        _out, err, status = run_raider('flow', 'init', '--project', dir)
+
+        expect(status.exitstatus).to eq(2)
+        expect(err).to include('Flows need a Selenium web project made with Ruby Raider 4.0 or later')
+      end
+    end
+
+    it 'exits 2 for a missing project folder' do
+      _out, err, status = run_raider('flow', 'init', '--project', '/nonexistent/raider')
+
+      expect(status.exitstatus).to eq(2)
+      expect(err).to include('Project folder not found')
+    end
+  end
+
+  it 'offers --notify on flow run and flow schedule' do
+    run_help, = run_raider('flow', 'help', 'run')
+    schedule_help, = run_raider('flow', 'help', 'schedule')
+
+    expect([run_help, schedule_help]).to all(include('--notify'))
+  end
+
+  describe 'schedules' do
+    # Only paths refused before the OS scheduler is asked: this machine's launchd is real
+    it 'lists schedule, unschedule and schedules in raider flow help' do
+      out, _err, status = run_raider('flow', 'help')
+
+      expect(status.exitstatus).to eq(0)
+      expect(out).to include('flow schedule NAME', 'flow unschedule NAME', 'flow schedules')
+    end
+
+    it 'dispatches raider flow schedule NAME to schedule, not schedules' do
+      Dir.mktmpdir('flow-schedule') do |dir|
+        _out, err, status = run_raider('flow', 'schedule', 'x', '--every', 'day', '--at', '08:00', '--project', dir)
+
+        expect(status.exitstatus).to eq(2)
+        expect(err).to include('No flow x: flows/x_flow.rb not found')
+      end
+    end
+
+    it 'exits 2 through the rule check when --every is left out' do
+      Dir.mktmpdir('flow-schedule') do |dir|
+        %w[flows/flow_helper.rb flows/support/run.rb flows/report_flow.rb].each do |file|
+          FileUtils.mkdir_p(File.dirname(File.join(dir, file)))
+          File.write(File.join(dir, file), '')
+        end
+        _out, err, status = run_raider('flow', 'schedule', 'report', '--at', '08:00', '--project', dir)
+
+        expect(status.exitstatus).to eq(2)
+        expect(err).to include('Invalid every nil: use hour, day, weekday or week')
+      end
+    end
+
+    it 'exits 2 for an invalid name to unschedule' do
+      Dir.mktmpdir('flow-schedule') do |dir|
+        _out, err, status = run_raider('flow', 'unschedule', 'Bad-Name', '--project', dir)
+
+        expect(status.exitstatus).to eq(2)
+        expect(err).to include('Invalid flow name "Bad-Name"')
+      end
+    end
+
+    it 'exits 2 with a message for an argument that is not valid UTF-8' do
+      _out, err, status = run_raider('flow', 'schedule', "a\xFF".b, '--every', 'day')
+
+      expect(status.exitstatus).to eq(2)
+      expect(err).to eq("Invalid argument \"a\\xFF\": use valid UTF-8\n")
+    end
+
+    it 'says there are no schedules, as text and as JSON' do
+      Dir.mktmpdir('flow-schedule') do |dir|
+        text, = run_raider('flow', 'schedules', '--project', dir)
+        json, = run_raider('flow', 'schedules', '--json', '--project', dir)
+
+        expect([text, json]).to eq(["No schedules yet: raider flow schedule <name> --every day --at 08:00\n", "[]\n"])
+      end
+    end
+  end
+end

data/spec/generators/flow_helper_spec.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+# The flow templates are copied into projects by `raider flow init`
+RSpec.describe 'flow templates' do
+  let(:templates) { File.expand_path('../../lib/generators/templates', __dir__) }
+  let(:helper) { render('flows/flow_helper.tt') }
+
+  def render(relative) = ERB.new(File.read(File.join(templates, relative)), trim_mode: '-').result
+
+  it 'starts the run before loading spec_helper, so the lock and HEADLESS come before the driver' do
+    expect(helper.index('RaiderFlows::Run.start!')).to be < helper.index("require_relative '../helpers/spec_helper'")
+  end
+
+  it 'sends the report to the flow results folder without cleaning it, even when start! refuses the run' do
+    expect(helper).to match(/begin\n  RaiderFlows::Run.start!\nensure\n  RaiderFlows::Run.configure_reporter\nend/)
+    expect(render('flows/run.tt')).to include('reporter.output_dir = results_dir ||', 'reporter.clean_output_dir = false')
+  end
+
+  it 'never retries a flow inside one run' do
+    expect(helper).to include('config.default_retry_count = 0')
+  end
+
+  it 'marks the start of the steps after spec_helper set up the driver' do
+    expect(helper).to include('config.append_before(:each) { RaiderFlows::Run.steps_started! }')
+  end
+
+  it 'never sets the reporter output folder from spec_helper, so a test run cannot wipe flow results' do
+    spec_helper = File.read(File.join(templates, 'helpers/spec_helper.tt'))
+
+    expect(spec_helper).not_to match(/output_dir|clean_output_dir/)
+  end
+
+  it 'renders Ruby that parses' do
+    [helper, render('flows/run.tt')].each do |source|
+      expect { RubyVM::InstructionSequence.compile(source) }.not_to raise_error
+    end
+  end
+end

data/spec/integration/content/gemfile_content_spec.rb

@@ -85,8 +85,8 @@ describe 'Gemfile content' do
           expect(gemfile).to include("gem 'ruby_raider', '~> #{major_minor}'")
         end
 
-        it 'pins ruby_raider to the 4.0 release line' do
-          expect(gemfile).to include("gem 'ruby_raider', '~> 4.0'")
+        it 'pins ruby_raider to the 4.1 release line' do
+          expect(gemfile).to include("gem 'ruby_raider', '~> 4.1'")
         end
       end
     end

data/spec/integration/end_to_end_spec.rb

@@ -447,6 +447,69 @@ describe 'End-to-End Project Generation and Execution' do
     end
   end
 
+  # raider flow init and raider flow run on a generated Selenium project, headless, against a local page
+  context 'Flows', :slow do
+    let(:project) { generate_video_project('rspec', 'selenium') }
+
+    def write_flows(project)
+      page = File.join(File.expand_path(project), 'flow_page.html')
+      File.write(page, <<~HTML)
+        <!doctype html><title>Timesheet</title>
+        <label for="hours">Hours</label><input id="hours">
+        <button onclick="document.getElementById('done').textContent = 'Saved ' + document.getElementById('hours').value">Save</button>
+        <p id="done"></p>
+      HTML
+      { 'timesheet' => "driver.find_element(label: 'Hours').send_keys(flow_input('hours', '8'))\n    " \
+                       "driver.find_element(by_role('button', name: 'Save')).click\n    " \
+                       "driver.find_element(text: \"Saved \#{flow_input('hours', '8')}\")",
+        'export' => "driver.find_element(id: 'export').click" }.each do |name, steps|
+        File.write(File.join(project, "flows/#{name}_flow.rb"), <<~RUBY)
+          # frozen_string_literal: true
+
+          require_relative 'flow_helper'
+
+          RSpec.describe '#{name}' do
+            it 'runs' do
+              driver.navigate.to 'file://#{page}'
+              #{steps}
+            end
+          end
+        RUBY
+      end
+    end
+
+    def runs(project, name)
+      File.readlines(File.join(project, ".raider/flows/#{name}/runs.jsonl")).map { |line| JSON.parse(line) }
+    end
+
+    it 'runs a flow headless into flow-results and records completed and failed runs', :aggregate_failures do
+      skip 'Google Chrome is not installed' unless browser_installed?('chrome')
+      FileUtils.rm_rf([File.join(project, 'flows'), File.join(project, '.raider/flows'), File.join(project, 'flow-results')])
+
+      init = run_in_project(project, 'bundle exec raider flow init')
+      expect(init[:exit_code]).to eq(0), init[:stdout] + init[:stderr]
+      write_flows(project)
+      env = { 'VIDEO' => 'off', 'TRACE' => 'off', 'RAIDER_TOKEN' => nil, 'RAIDER_ENDPOINT' => nil }
+      completed = run_in_project(project, 'bundle exec raider flow run timesheet --input hours=7', env:)
+      failed = run_in_project(project, 'bundle exec raider flow run export', env: env.merge('RAIDER_TIMEOUT' => '1'))
+
+      expect(completed[:exit_code]).to eq(0), completed[:stdout] + completed[:stderr]
+      expect(completed[:stdout]).to match(%r{Flow timesheet completed in .* s\nResults: flow-results/timesheet/\d{8}T\d{6}Z})
+      expect(runs(project, 'timesheet').last).to include('status' => 'completed', 'trigger' => 'manual')
+      expect(failed[:exit_code]).to eq(1), failed[:stdout] + failed[:stderr]
+      expect(runs(project, 'export').last).to include('status' => 'failed', 'failed_step' => { 'title' => 'runs', 'line' => 8 })
+      expect(File).to exist(File.join(project, runs(project, 'export').last['results_dir'], 'run.json'))
+      expect(File).not_to exist(File.join(project, 'raider-results'))
+    end
+
+    it 'passes its own RuboCop with the flow files' do
+      FileUtils.rm_rf(File.join(project, 'flows'))
+      run_in_project(project, 'bundle exec raider flow init')
+
+      expect_project_rubocop_clean(project)
+    end
+  end
+
   # Trace replay against headless Chrome, and one example on headless Firefox. The page is served over HTTP from this process (never file://), so
   # WebDriver BiDi reports real network and console entries. raider_reporter ~> 1.0 resolves from RubyGems, or
   # from a checkout at RAIDER_REPORTER_PATH. The example with video on also needs RAIDER_FFMPEG_PATH.

data/spec/integration/flows/flow_project.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'fileutils'
+
+# A project with the flow files `raider flow init` writes and a stand-in helpers/spec_helper.rb:
+# no browser and no raider_reporter. FAKE_DRIVER_FAIL makes the driver fail in before(:each);
+# FAKE_STEPS writes a run.json whose desktop step map names step 2 of flows/recorded_flow.rb.
+module FlowProject
+  TEMPLATES = File.expand_path('../../../lib/generators/templates/flows', __dir__)
+
+  STUB_SPEC_HELPER = <<~RUBY
+    # frozen_string_literal: true
+
+    require 'json'
+    require 'rspec'
+
+    module RaiderReporter
+      Config = Struct.new(:output_dir, :clean_output_dir)
+      def self.configuration = (@configuration ||= Config.new(output_dir: 'raider-results', clean_output_dir: true))
+      def self.configure = yield(configuration)
+    end
+
+    # What the real reporter would write to and clean, for the specs to read
+    at_exit { File.write('reporter.json', JSON.generate(RaiderReporter.configuration.to_h)) }
+
+    module DriverHelper
+      def driver
+        raise 'the driver could not start' if ENV['FAKE_DRIVER_FAIL']
+
+        @driver ||= Object.new
+      end
+    end
+
+    RSpec.configure do |config|
+      config.include(DriverHelper)
+      config.before(:each) { driver }
+      config.after(:each) { File.write('driver_quit', '') }
+      # The real reporter writes run.json when it closes; the desktop sidecar names the failed step there
+      config.after(:suite) do
+        dir = RaiderReporter.configuration.output_dir
+        steps = { 'items' => [{ 'id' => 's1', 'title' => 'open' }, { 'id' => 's2', 'title' => 'click "Export"' }], 'failed' => 1 }
+        results = [{ 'file_path' => 'flows/recorded_flow.rb', 'status' => 'failed', 'steps' => steps }]
+        File.write(File.join(dir, 'run.json'), JSON.generate('results' => results)) if dir && ENV['FAKE_STEPS']
+      end
+    end
+  RUBY
+
+  module_function
+
+  def build(dir, flows)
+    FileUtils.mkdir_p(File.join(dir, 'flows/support'))
+    FileUtils.mkdir_p(File.join(dir, 'helpers'))
+    File.write(File.join(dir, 'flows/flow_helper.rb'), render('flow_helper.tt'))
+    File.write(File.join(dir, 'flows/support/run.rb'), render('run.tt'))
+    File.write(File.join(dir, 'helpers/spec_helper.rb'), STUB_SPEC_HELPER)
+    File.write(File.join(dir, '.rspec'), "-I .\n--require helpers/spec_helper\n")
+    flows.each { |name, source| File.write(File.join(dir, "flows/#{name}_flow.rb"), source) }
+  end
+
+  def render(name) = ERB.new(File.read(File.join(TEMPLATES, name)), trim_mode: '-').result
+end

data/spec/integration/flows/run_command_spec.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'tmpdir'
+require_relative 'flow_project'
+
+# `raider flow run` and `raider flow list` against a project with its own Gemfile, from another folder.
+RSpec.describe 'raider flow run and list' do
+  raider = File.expand_path('../../../bin/raider', __dir__)
+
+  flows = {
+    'ok' => <<~RUBY,
+      require_relative 'flow_helper'
+
+      RSpec.describe 'ok' do
+        it('runs every step') { puts "who=\#{flow_input('who', 'nobody')} headless=\#{ENV.fetch('HEADLESS', 'unset')}" }
+      end
+    RUBY
+    'broken' => <<~RUBY
+      require_relative 'flow_helper'
+
+      RSpec.describe 'broken' do
+        it 'downloads the report' do
+          raise 'no such element'
+        end
+      end
+    RUBY
+  }
+
+  # Built once: bundling the project is the slow part
+  dir = nil
+
+  before(:context) do # rubocop:disable RSpec/BeforeAfterAll
+    dir = File.realpath(Dir.mktmpdir('flow-command'))
+    FlowProject.build(dir, flows)
+    File.write(File.join(dir, 'Gemfile'), "source 'https://rubygems.org'\ngem 'rspec'\n")
+    _out, err, status = Bundler.with_unbundled_env do
+      Open3.capture3('bundle', 'install', '--prefer-local', '--quiet', chdir: dir)
+    end
+    raise "bundle install failed: #{err}" unless status.success?
+  end
+
+  after(:context) { FileUtils.rm_rf(dir) } # rubocop:disable RSpec/BeforeAfterAll
+
+  define_method(:raider_flow) do |*args|
+    out, err, status = Open3.capture3(RbConfig.ruby, raider, 'flow', *args, '--project', dir, chdir: Dir.tmpdir)
+    [out, err, status.exitstatus]
+  end
+
+  it 'runs a completed flow, passing inputs and headless through, and exits 0' do
+    out, _err, code = raider_flow('run', 'ok', '--input', 'who=ada')
+
+    expect(code).to eq(0)
+    expect(out).to include('who=ada headless=true', 'Flow ok completed in ')
+    expect(out).to match(%r{^Results: flow-results/ok/\d{8}T\d{6}Z(-\d+)?$})
+  end
+
+  it 'exits 1 and names the failed line' do
+    out, _err, code = raider_flow('run', 'broken')
+
+    expect(code).to eq(1)
+    expect(out).to include('Flow broken failed at line 5 (downloads the report)')
+  end
+
+  it 'exits 2 for a flow that does not exist' do
+    _out, err, code = raider_flow('run', 'missing')
+
+    expect(code).to eq(2)
+    expect(err).to include('No flow missing: flows/missing_flow.rb not found')
+  end
+
+  it 'lists every flow with its last result as JSON for the desktop' do
+    raider_flow('run', 'ok')
+    out, _err, code = raider_flow('list', '--json')
+    listed = JSON.parse(out)
+
+    expect(code).to eq(0)
+    expect(listed.map { |flow| flow['name'] }).to eq(%w[broken ok])
+    expect(listed.last).to include('file' => 'flows/ok_flow.rb')
+    expect(listed.last['last'].keys).to eq(%w[status finished_at failed_step results_dir])
+    expect(listed.last['last']['status']).to eq('completed')
+  end
+
+  it 'lists flows as text' do
+    raider_flow('run', 'ok')
+    out, = raider_flow('list')
+
+    expect(out).to match(/^ok\s+completed\s+\d{4}-\d\d-\d\dT/)
+  end
+end