ruby_raider 3.10.0 → 3.11.0

data/spec/integration/content/readme_content_spec.rb

@@ -112,4 +112,32 @@ describe 'Generated Readme content' do
       end
     end
   end
+
+  FRAMEWORKS.product(AUTOMATION_TYPES).each do |framework, automation|
+    context "with #{framework} and #{automation}, the login reuse section" do
+      subject(:readme) { read_generated("#{framework}_#{automation}", 'Readme.md') }
+
+      if %w[selenium watir].include?(automation)
+        it 'documents the tags, other roles, max_age, the env switch and the secrets warning' do
+          section = readme[/^## Reusing the login\n.*?(?=^##)/m].gsub(/\s+/, ' ')
+          expect(section).to include('`:logged_in`', '`@logged_in`', "SessionState.new(driver, name: 'admin')",
+                                     'browser.driver', 'login_state', 'max_age', 'RAIDER_LOGIN_STATE=off',
+                                     'RAIDER_LOGIN_STATE=refresh', '.raider/auth/', 'git-ignored',
+                                     'live session tokens', 'must not be committed, cached or uploaded')
+        end
+
+        it 'is its own ## section, straight after the Quality gate and before any CI section' do
+          heading = readme.index("\n## Reusing the login\n")
+          gate = readme.index("\n### Quality gate\n")
+          expect(gate).to be < heading
+          expect(readme[(gate + 1)...heading]).not_to match(/\n##/)
+          expect(readme[(heading + 1)..][/\n## .*/]).to be_nil.or match(/\A\n## (CI|Azure Pipelines)\z/)
+        end
+      else
+        it 'does not mention login reuse' do
+          expect(readme).not_to include('Reusing the login', 'RAIDER_LOGIN_STATE', '.raider/auth/')
+        end
+      end
+    end
+  end
 end

data/spec/integration/content/syntax_validation_spec.rb

@@ -24,6 +24,21 @@ describe 'Ruby syntax validation' do
             expect(content).to have_frozen_string_literal
           end
         end
+
+        login_reuse_files = %w[helpers/session_state.rb]
+        login_reuse_files += if framework == 'rspec'
+                               %w[helpers/spec_helper.rb]
+                             else
+                               %w[features/support/env.rb features/step_definitions/login_steps.rb]
+                             end
+
+        login_reuse_files.each do |relative|
+          it "#{relative} is generated as valid Ruby with frozen_string_literal" do
+            content = File.read(File.join(project_name, relative))
+            expect(content).to have_valid_ruby_syntax
+            expect(content).to have_frozen_string_literal
+          end
+        end
       end
     end
   end

data/spec/integration/content/test_content_spec.rb

@@ -116,18 +116,41 @@ describe 'Test file content' do
     end
   end
 
+  shared_examples 'logged in example' do |project_name|
+    it 'adds a :logged_in example that reuses the saved login and keeps the login example' do
+      spec = read_generated(project_name, 'spec/login_page_spec.rb')
+      expect(spec).to include("describe 'Account', :logged_in", 'opens the account page with the saved login',
+                              "describe 'Login' do", 'can successfully log in')
+    end
+  end
+
+  shared_examples 'logged in scenario' do |project_name|
+    it 'adds a @logged_in scenario and keeps the login scenario' do
+      feature = read_generated(project_name, 'features/login.feature')
+      expect(feature).to include("@logged_in\nScenario: A logged-in user opens the account page",
+                                 "Given I'm a registered user\n", 'Scenario: A user can login')
+    end
+
+    it 'defines the step that picks the user without logging in' do
+      steps = read_generated(project_name, 'features/step_definitions/login_steps.rb')
+      expect(steps).to include(%q(Given("I'm a {user}") do |user|))
+    end
+  end
+
   # --- RSpec contexts ---
 
   context 'with rspec and selenium' do
     name = "#{FrameworkIndex::RSPEC}_#{AutomationIndex::SELENIUM}"
     include_examples 'valid rspec spec', name
     include_examples 'selenium rspec spec', name
+    include_examples 'logged in example', name
   end
 
   context 'with rspec and watir' do
     name = "#{FrameworkIndex::RSPEC}_#{AutomationIndex::WATIR}"
     include_examples 'valid rspec spec', name
     include_examples 'watir rspec spec', name
+    include_examples 'logged in example', name
   end
 
   # --- Cucumber contexts ---
@@ -138,6 +161,7 @@ describe 'Test file content' do
     include_examples 'valid cucumber env', name
     include_examples 'valid cucumber world', name
     include_examples 'valid cucumber config', name
+    include_examples 'logged in scenario', name
   end
 
   context 'with cucumber and watir' do
@@ -146,5 +170,6 @@ describe 'Test file content' do
     include_examples 'valid cucumber env', name
     include_examples 'valid cucumber world', name
     include_examples 'valid cucumber config', name
+    include_examples 'logged in scenario', name
   end
 end

data/spec/integration/end_to_end_spec.rb

@@ -269,6 +269,29 @@ describe 'End-to-End Project Generation and Execution' do
   context 'Web Automation Frameworks' do
     describe 'Selenium + RSpec' do
       include_examples 'executable rspec project', 'rspec_selenium'
+
+      it 'saves the login once and reuses it', :aggregate_failures, :slow do
+        skip 'Bundle install failed' unless bundle_install('rspec_selenium')
+
+        state_file = File.join('rspec_selenium', '.raider', 'auth', 'user.json')
+        FileUtils.rm_rf(File.join('rspec_selenium', '.raider'))
+        first = run_in_project('rspec_selenium', 'bundle exec rspec spec/', env: { 'HEADLESS' => 'true' })
+        failed = ->(run, index) { "Run #{index} failed.\nSTDOUT: #{run[:stdout]}\nSTDERR: #{run[:stderr]}" }
+        raise failed.call(first, 1) unless first[:exit_code].zero? # show run 1's output, not a missing state file
+
+        expect(File).to exist(state_file)
+        saved = JSON.parse(File.read(state_file))
+        second = run_in_project('rspec_selenium', 'bundle exec rspec spec/', env: { 'HEADLESS' => 'true' })
+        expect(second[:exit_code]).to eq(0), failed.call(second, 2)
+        expect(File.stat(state_file).mode & 0o777).to eq(0o600)
+        expect(saved).to include('format' => 1, 'origin' => 'https://raider-test-site.onrender.com')
+        expect(JSON.parse(File.read(state_file))['saved_at']).to eq(saved['saved_at'])
+        cookie_values = saved['cookies'].map { |cookie| cookie['value'].to_s }
+        expect(cookie_values.reject(&:empty?)).not_to be_empty
+        output = [first, second].map { |run| run[:stdout] + run[:stderr] }.join
+        # Short values like "1" or "en" can appear in any output; a leaked token is long.
+        cookie_values.select { |value| value.length >= 8 }.each { |value| expect(output).not_to include(value) }
+      end
     end
 
     describe 'Watir + RSpec' do

data/spec/integration/generators/helpers_generator_spec.rb

@@ -10,6 +10,18 @@ describe HelpersGenerator do
     end
   end
 
+  shared_examples 'creates a session state helper' do |name|
+    it 'creates a session state helper file' do
+      expect(File).to exist("#{name}/helpers/session_state.rb")
+    end
+  end
+
+  shared_examples 'skips the session state helper' do |name|
+    it 'does not create a session state helper file' do
+      expect(File).not_to exist("#{name}/helpers/session_state.rb")
+    end
+  end
+
   shared_examples 'creates selenium helpers' do |name|
     it 'creates a driver helper file' do
       expect(File).to exist("#{name}/helpers/driver_helper.rb")
@@ -42,54 +54,63 @@ describe HelpersGenerator do
 
   context 'with rspec and selenium' do
     include_examples 'creates common helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::SELENIUM}"
+    include_examples 'creates a session state helper', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::SELENIUM}"
     include_examples 'creates selenium helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::SELENIUM}"
     include_examples 'creates rspec helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::SELENIUM}"
   end
 
   context 'with rspec and watir' do
     include_examples 'creates common helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::WATIR}"
+    include_examples 'creates a session state helper', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::WATIR}"
     include_examples 'creates watir helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::WATIR}"
     include_examples 'creates rspec helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::WATIR}"
   end
 
   context 'with cucumber and selenium' do
     include_examples 'creates common helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::SELENIUM}"
+    include_examples 'creates a session state helper', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::SELENIUM}"
     include_examples 'creates selenium helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::SELENIUM}"
     include_examples 'creates cucumber helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::SELENIUM}"
   end
 
   context 'with cucumber and watir' do
     include_examples 'creates common helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::WATIR}"
+    include_examples 'creates a session state helper', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::WATIR}"
     include_examples 'creates watir helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::WATIR}"
     include_examples 'creates cucumber helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::WATIR}"
   end
 
   context 'with rspec and appium android' do
     include_examples 'creates common helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::ANDROID}"
+    include_examples 'skips the session state helper', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::ANDROID}"
     include_examples 'creates selenium helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::ANDROID}"
     include_examples 'creates rspec helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::ANDROID}"
   end
 
   context 'with rspec and appium ios' do
     include_examples 'creates common helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::IOS}"
+    include_examples 'skips the session state helper', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::IOS}"
     include_examples 'creates selenium helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::IOS}"
     include_examples 'creates rspec helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::IOS}"
   end
 
   context 'with cucumber and appium android' do
     include_examples 'creates common helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::ANDROID}"
+    include_examples 'skips the session state helper', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::ANDROID}"
     include_examples 'creates selenium helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::ANDROID}"
     include_examples 'creates cucumber helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::ANDROID}"
   end
 
   context 'with cucumber and appium ios' do
     include_examples 'creates common helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::IOS}"
+    include_examples 'skips the session state helper', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::IOS}"
     include_examples 'creates selenium helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::IOS}"
     include_examples 'creates cucumber helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::IOS}"
   end
 
   context 'with rspec and appium cross platform' do
     include_examples 'creates common helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::CROSS_PLATFORM}"
+    include_examples 'skips the session state helper', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::CROSS_PLATFORM}"
     include_examples 'creates selenium helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::CROSS_PLATFORM}"
     include_examples 'creates rspec helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::CROSS_PLATFORM}"
     include_examples 'creates cross platform helpers', "#{FrameworkIndex::RSPEC}_#{AutomationIndex::CROSS_PLATFORM}"
@@ -97,6 +118,7 @@ describe HelpersGenerator do
 
   context 'with cucumber and appium cross platform' do
     include_examples 'creates common helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::CROSS_PLATFORM}"
+    include_examples 'skips the session state helper', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::CROSS_PLATFORM}"
     include_examples 'creates selenium helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::CROSS_PLATFORM}"
     include_examples 'creates cucumber helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::CROSS_PLATFORM}"
     include_examples 'creates cross platform helpers', "#{FrameworkIndex::CUCUMBER}_#{AutomationIndex::CROSS_PLATFORM}"

data/spec/integration/helpers/session_state_spec.rb

@@ -0,0 +1,428 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'json'
+require 'selenium-webdriver'
+require 'time'
+require 'tmpdir'
+require 'yaml'
+
+module SessionStateSpec
+  TEMPLATE = File.expand_path('../../../lib/generators/templates/helpers/session_state.tt', __dir__)
+
+  # Renders the template and loads it from a temp file that is removed straight away.
+  def self.load_template
+    Dir.mktmpdir('session_state_tt') do |dir|
+      file = File.join(dir, 'session_state.rb')
+      File.write(file, ERB.new(File.read(TEMPLATE), trim_mode: '-').result)
+      load file
+    end
+  end
+end
+SessionStateSpec.load_template
+
+module SessionStateSpec
+  # Implements exactly the driver calls SessionState uses and records them in order.
+  class FakeDriver
+    ORIGIN_URL = 'https://raider-test-site.onrender.com/account'
+
+    def initialize(cookies: [], local: {}, session: {}, reject: nil, url: ORIGIN_URL)
+      @reject = reject
+      @page = { cookies:, url: }
+      @storage = { 'localStorage' => local, 'sessionStorage' => session }
+      @log = { calls: [], added: [] }
+    end
+
+    def calls = @log[:calls]
+    def added = @log[:added]
+    def local = @storage['localStorage']
+    def session = @storage['sessionStorage']
+
+    def manage = self
+    def navigate = self
+    def all_cookies = @page[:cookies]
+    def current_url = @page[:url]
+    def refresh = calls << :refresh
+    def delete_all_cookies = calls << :delete_all_cookies
+
+    def add_cookie(cookie)
+      raise 'rejected' if @reject&.call(cookie)
+
+      calls << :add_cookie
+      added << cookie
+    end
+
+    def to(url)
+      @page[:url] = url
+      calls << [:to, url]
+    end
+
+    def execute_script(_script, *args)
+      kind, values = args
+      return @storage[kind] if values.nil?
+
+      calls << [:write, kind]
+      @storage[kind] = values
+    end
+  end
+
+  # The browser end of a real Selenium::WebDriver::Manager: records the wire payloads it receives.
+  class FakeBridge
+    def initialize(log, reject)
+      @log = log
+      @reject = reject
+    end
+
+    def add_cookie(cookie)
+      raise Selenium::WebDriver::Error::InvalidArgumentError, 'rejected' if @reject&.call(cookie)
+
+      @log[:calls] << :add_cookie
+      @log[:added] << cookie
+    end
+
+    def delete_all_cookies = @log[:calls] << :delete_all_cookies
+    def cookies = []
+  end
+
+  # A FakeDriver whose manage is the real Selenium Manager, so its key translation is under test.
+  class ManagedDriver < FakeDriver
+    def manage
+      @manage ||= Selenium::WebDriver::Manager.new(FakeBridge.new(@log, @reject))
+    end
+  end
+end
+
+describe 'SessionState' do
+  let(:url) { 'https://raider-test-site.onrender.com/' }
+  let(:driver) { SessionStateSpec::FakeDriver.new(cookies:, local: { 'token' => 'abc' }, session: { 'tab' => '1' }) }
+  let(:state) { SessionState.new(driver) }
+  let(:config) { { 'url' => url } }
+
+  def origin = 'https://raider-test-site.onrender.com'
+  def state_file = File.join('.raider', 'auth', 'user.json')
+
+  def cookies
+    [{ name: 'sid', value: 's3cr3t', domain: 'raider-test-site.onrender.com', path: '/', expires: nil,
+       secure: true, http_only: true, same_site: 'Lax' }]
+  end
+
+  around do |example|
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        FileUtils.mkdir_p('config')
+        example.run
+      end
+    end
+  end
+
+  before do
+    File.write('config/config.yml', YAML.dump(config))
+    stub_const('ENV', ENV.to_h.merge('RAIDER_LOGIN_STATE' => nil))
+  end
+
+  def write_state(overrides = {})
+    FileUtils.mkdir_p(File.dirname(state_file))
+    data = { 'format' => 1, 'name' => 'user', 'origin' => origin, 'saved_at' => (Time.now.utc - 10).iso8601,
+             'cookies' => [], 'local_storage' => {}, 'session_storage' => {} }.merge(overrides)
+    File.write(state_file, JSON.generate(data))
+  end
+
+  def saved
+    JSON.parse(File.read(state_file))
+  end
+
+  def saved_cookie(name, **attrs)
+    { 'name' => name, 'value' => 'v', 'domain' => 'raider-test-site.onrender.com', 'path' => '/',
+      'expires' => nil, 'secure' => false, 'http_only' => false, 'same_site' => nil }.merge(attrs.transform_keys(&:to_s))
+  end
+
+  it 'rejects a name outside [a-z0-9_-]' do
+    expect { SessionState.new(driver, name: '../x') }.to raise_error(ArgumentError)
+    expect { SessionState.new(driver, name: 'Admin') }.to raise_error(ArgumentError)
+  end
+
+  it 'saves format 1 with origin, saved_at, cookies and both storages' do
+    state.save
+    expect(saved).to include('format' => 1, 'name' => 'user', 'origin' => origin,
+                             'local_storage' => { 'token' => 'abc' }, 'session_storage' => { 'tab' => '1' })
+    expect { Time.iso8601(saved['saved_at']) }.not_to raise_error
+    expect(saved['cookies'].first).to include('name' => 'sid', 'http_only' => true, 'secure' => true)
+  end
+
+  it 'writes the file 0600 in a 0700 directory, atomically' do
+    state.save
+    expect(File.stat(state_file).mode & 0o777).to eq(0o600)
+    expect(File.stat(File.dirname(state_file)).mode & 0o777).to eq(0o700)
+    expect(Dir.glob('.raider/auth/*.tmp')).to be_empty
+  end
+
+  context 'with a url that has a port and a path' do
+    let(:url) { 'https://x.test:8443/app/' }
+
+    it 'derives the origin without path or trailing slash' do
+      state.save
+      expect(saved['origin']).to eq('https://x.test:8443')
+    end
+  end
+
+  describe '#save on another origin' do
+    it 'goes back to the origin before reading when the login ended elsewhere' do
+      sso = SessionStateSpec::FakeDriver.new(url: 'https://sso.other.test/x')
+      SessionState.new(sso).save
+      expect(sso.calls).to eq([[:to, "#{origin}/"]])
+    end
+
+    it 'stays put when the login ended on the origin' do
+      state.save
+      expect(driver.calls).to be_empty
+    end
+  end
+
+  describe '#fresh?' do
+    it 'is false when the file is missing' do
+      expect(state.fresh?).to be(false)
+    end
+
+    it 'is true for a recent file of the same format and origin' do
+      write_state
+      expect(state.fresh?).to be(true)
+    end
+
+    it 'is false for another format, another origin or an old file' do
+      write_state('format' => 2)
+      expect(state.fresh?).to be(false)
+      write_state('origin' => 'https://other.test')
+      expect(state.fresh?).to be(false)
+      write_state('saved_at' => (Time.now.utc - 3601).iso8601)
+      expect(state.fresh?).to be(false)
+    end
+
+    context 'with login_state max_age 30' do
+      let(:config) { { 'url' => url, 'login_state' => { 'max_age' => 30 } } }
+
+      it 'is false for a file older than max_age' do
+        write_state('saved_at' => (Time.now.utc - 59).iso8601)
+        expect(state.fresh?).to be(false)
+      end
+    end
+  end
+
+  describe '#restore' do
+    let(:driver) { SessionStateSpec::ManagedDriver.new }
+
+    it 'restores live cookies for the origin and skips expired and foreign ones' do
+      write_state('cookies' => [
+                    saved_cookie('session'),
+                    saved_cookie('future', expires: (Time.now.utc + 86_400).iso8601),
+                    saved_cookie('past', expires: (Time.now.utc - 1).iso8601),
+                    saved_cookie('dotted', domain: '.raider-test-site.onrender.com'),
+                    saved_cookie('foreign', domain: 'other.com')
+                  ], 'local_storage' => { 'a' => 'b' })
+      warning = "[login_state] 2 cookies skipped (expired or another domain) from #{state_file}\n"
+      expect { expect(state.restore).to be(true) }.to output(warning).to_stderr
+      expect(driver.added.map { |c| c[:name] }).to eq(%w[session future dotted])
+      expect(driver.calls).to eq([[:to, "#{origin}/"], :delete_all_cookies, :add_cookie, :add_cookie, :add_cookie,
+                                  [:write, 'localStorage'], [:write, 'sessionStorage'], :refresh])
+    end
+
+    it 'hands Selenium the cookie keys it translates to the wire format' do
+      write_state('cookies' => [saved_cookie('session', same_site: 'Lax', http_only: true),
+                                saved_cookie('future', expires: (Time.now.utc + 86_400).iso8601)])
+      expect(state.restore).to be(true)
+      expect(driver.added.first).to include(sameSite: 'Lax', httpOnly: true, secure: false)
+      expect(driver.added.flat_map(&:keys)).not_to include(:same_site, :http_only, :expires)
+      expect(driver.added.last[:expiry]).to be_a(Integer)
+    end
+
+    it 'returns false and warns for corrupt JSON' do
+      FileUtils.mkdir_p(File.dirname(state_file))
+      File.write(state_file, '{"format":')
+      expect { expect(state.restore).to be(false) }.to output(/\[login_state\].*user\.json/).to_stderr
+    end
+  end
+
+  it 'never prints cookie or storage values' do
+    leak = /s3cr3t|abc/
+    expect do
+      expect do
+        state.save
+        state.restore
+        write_state('cookies' => [saved_cookie('x', value: 's3cr3t')], 'local_storage' => { 'k' => 'abc' })
+        state.reuse(valid: -> { false }) { nil }
+      end.not_to output(leak).to_stdout
+    end.not_to output(leak).to_stderr
+  end
+
+  describe 'unsupported or unusable files' do
+    it 'warns once, naming the file, for another format' do
+      write_state('format' => 2)
+      expect { expect(state.restore).to be(false) }.to output(/\A\[login_state\] #{Regexp.escape(state_file)} has an unsupported format.*\n\z/).to_stderr
+    end
+
+    it 'stays silent for a missing, expired or other-origin file' do
+      expect do
+        state.fresh?
+        write_state('origin' => 'https://other.test')
+        state.fresh?
+        write_state('saved_at' => (Time.now.utc - 7200).iso8601)
+        state.fresh?
+      end.not_to output.to_stderr
+    end
+
+    it 'retries a cookie the browser rejects without sameSite' do
+      rejecting = SessionStateSpec::ManagedDriver.new(reject: ->(cookie) { cookie.key?(:sameSite) })
+      write_state('cookies' => [saved_cookie('a', same_site: 'None')])
+      expect(SessionState.new(rejecting).restore).to be(true)
+      expect(rejecting.added.map { |c| [c[:name], c.key?(:sameSite)] }).to eq([['a', false]])
+    end
+  end
+
+  describe '#reuse' do
+    def run_reuse(**options)
+      count = 0
+      silence { state.reuse(**options) { count += 1 } }
+      count
+    end
+
+    def silence
+      original = $stderr
+      $stderr = StringIO.new
+      yield
+    ensure
+      $stderr = original
+    end
+
+    def warnings
+      original = $stderr
+      $stderr = StringIO.new
+      yield
+      $stderr.string
+    ensure
+      $stderr = original
+    end
+
+    it 'logs in and saves when there is no file' do
+      expect(run_reuse).to eq(1)
+      expect(File).to exist(state_file)
+      expect(driver.calls).not_to include(:delete_all_cookies)
+    end
+
+    it 'clears the restored cookies and storage before the fallback login' do
+      managed = SessionStateSpec::ManagedDriver.new
+      write_state('cookies' => [saved_cookie('a')], 'local_storage' => { 'k' => 'v' })
+      silence { SessionState.new(managed).reuse(valid: -> { false }) { managed.calls << :login } }
+      after_refresh = managed.calls.drop(managed.calls.index(:refresh) + 1)
+      expect(after_refresh).to eq([:delete_all_cookies, [:write, 'localStorage'], [:write, 'sessionStorage'], :login])
+      expect(managed.local).to eq({})
+    end
+
+    it 'clears a half-applied restore before the fallback login' do
+      broken = SessionStateSpec::ManagedDriver.new(reject: ->(_cookie) { true })
+      write_state('cookies' => [saved_cookie('a')])
+      silence { SessionState.new(broken).reuse { broken.calls << :login } }
+      expect(broken.calls.last(4)).to eq([:delete_all_cookies, [:write, 'localStorage'], [:write, 'sessionStorage'],
+                                          :login])
+    end
+
+    it 'logs in without saving, with one warning, when the auth directory cannot be created' do
+      FileUtils.mkdir_p('.raider')
+      File.chmod(0o500, '.raider')
+      count = 0
+      output = warnings { expect(state.reuse { count += 1 }).to be(true) }
+      expect(count).to eq(1)
+      expect(output.lines).to match([start_with('[login_state] ')])
+    ensure
+      File.chmod(0o700, '.raider')
+    end
+
+    it 'logs in without saving, with one warning, when the lock cannot be opened' do
+      FileUtils.mkdir_p(File.join('.raider', 'auth', 'user.lock'))
+      count = 0
+      output = warnings { expect(state.reuse { count += 1 }).to be(true) }
+      expect(count).to eq(1)
+      expect(output.lines).to match([start_with('[login_state] ')])
+      expect(File).not_to exist(state_file)
+    end
+
+    it 'keeps the login, with one warning naming the file, when saving after it fails' do
+      allow(driver).to receive(:execute_script).and_raise(Selenium::WebDriver::Error::JavascriptError, 'abc')
+      count = 0
+      output = warnings { expect(state.reuse { count += 1 }).to be(true) }
+      expect(count).to eq(1)
+      expect(output.lines).to match([include(state_file, 'JavascriptError')])
+      expect(output).not_to include('abc')
+    end
+
+    it 'restores and skips the login when fresh and valid' do
+      write_state
+      expect(run_reuse(valid: -> { true })).to eq(0)
+      expect(driver.calls).to include(:refresh)
+    end
+
+    it 'falls back once when valid returns false' do
+      write_state('saved_at' => (Time.now.utc - 100).iso8601)
+      before = Time.iso8601(saved['saved_at'])
+      expect(run_reuse(valid: -> { false })).to eq(1)
+      expect(Time.iso8601(saved['saved_at'])).to be > before
+    end
+
+    it 'falls back when the file is corrupt' do
+      FileUtils.mkdir_p(File.dirname(state_file))
+      File.write(state_file, '{"format":')
+      expect(run_reuse).to eq(1)
+      expect(saved['format']).to eq(1)
+    end
+
+    it 'falls back once, with one warning, when valid raises' do
+      write_state
+      count = 0
+      expect { state.reuse(valid: -> { raise 'boom' }) { count += 1 } }.to output(/\A\[login_state\] validity check failed \(RuntimeError\), logging in again\n\z/).to_stderr
+      expect(count).to eq(1)
+    end
+
+    it 'falls back once, with one warning, when restore raises' do
+      write_state('cookies' => [saved_cookie('a')])
+      broken = SessionStateSpec::FakeDriver.new(reject: ->(_cookie) { true })
+      count = 0
+      expect { SessionState.new(broken).reuse { count += 1 } }.to output(/\A\[login_state\] could not restore.*\n\z/).to_stderr
+      expect(count).to eq(1)
+    end
+
+    it 'warns once for another format and logs in' do
+      write_state('format' => 2)
+      count = 0
+      expect { state.reuse { count += 1 } }.to output(/\A\[login_state\] .*unsupported format.*\n\z/).to_stderr
+      expect(count).to eq(1)
+    end
+
+    it 'RAIDER_LOGIN_STATE=off logs in and does not touch the disk' do
+      stub_const('ENV', ENV.to_h.merge('RAIDER_LOGIN_STATE' => 'off'))
+      expect(run_reuse).to eq(1)
+      expect(File).not_to exist('.raider')
+    end
+
+    it 'RAIDER_LOGIN_STATE=refresh logs in even when fresh' do
+      write_state('saved_at' => (Time.now.utc - 100).iso8601)
+      before = Time.iso8601(saved['saved_at'])
+      stub_const('ENV', ENV.to_h.merge('RAIDER_LOGIN_STATE' => 'refresh'))
+      expect(run_reuse).to eq(1)
+      expect(Time.iso8601(saved['saved_at'])).to be > before
+    end
+
+    it 'serializes concurrent callers on the lock' do
+      count = 0
+      drivers = Array.new(2) { SessionStateSpec::FakeDriver.new(cookies:) }
+      threads = drivers.map do |fake|
+        Thread.new do
+          SessionState.new(fake).reuse do
+            sleep 0.2
+            count += 1
+          end
+        end
+      end
+      threads.each(&:join)
+      expect(count).to eq(1)
+      expect(drivers.count { |fake| fake.calls.include?(:refresh) }).to eq(1)
+    end
+  end
+end