capybara-experience 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e02e512f097c443001b574db746c0d6e5922b82637a2a6c64cf2b2a995799360
-  data.tar.gz: 6ea77b1f4fab8368b9076583e68b31e983f518ab1e756455b4085230a8adc654
+  metadata.gz: a53a92480b4d79fbf507661277b1c0cfa31379910365cf770ee299875141d68a
+  data.tar.gz: d782f04061591b1923d046fd0300a470751fa2a58b273a079b5b93dbcb9b5b33
 SHA512:
-  metadata.gz: c6eba6b3d672f4b7d9fb8196b26c65933ad971fe627f98d5b867e512e945933bb93e0d72fd3639c562e4a12af70d20ba41968f43f4be0ef1dbe083fbc181f4c6
-  data.tar.gz: b65f2ccf7c79ef6351298682502e8ec502d0084f6043dfe66ae0a73464ec863c647843645246b53ea6ec68a83ea03aeaad3d79c998395267b86a68e4c7b47394
+  metadata.gz: cd3a3f5bd81acb16ec0e449f04bb8ea0d71c66d15d382216a927823d145bd1fa8f39d55d6f868250ef65b42f32451a158e5f6c9898225ad554a7f1fd3907f610
+  data.tar.gz: 7ada0747083edb9c37edf820045f963f24dc39b5b769d6e5a79808baeadadcf91d4023564632e29ad72fc3d91850cb818ed60cdf1b1ec234660b37bf627f7893

data/CLAUDE.md

@@ -0,0 +1,29 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+capybara-experience is a Ruby gem that extends Capybara with session pooling, multi-user experience objects, and a behavior DSL for feature tests. It lets tests instantiate multiple `Capybara::Experience` objects that each get their own browser session from a shared pool, enabling tests that compare different user journeys side by side.
+
+## Commands
+
+- **Run all tests:** `bundle exec rake` or `bundle exec rspec`
+- **Run a single test:** `bundle exec rspec spec/capybara/experience_spec.rb`
+- **Install deps:** `bundle install`
+- **Build gem:** `bundle exec rake build`
+- **Release gem:** `bundle exec rake release`
+
+## Architecture
+
+Three core components, all under `Capybara::Experience`:
+
+**`Experience`** (`lib/capybara/experience.rb`) — Includes `Capybara::DSL`. Each instance lazily acquires a session from the Pool via `page`. The `UnifySessionPool` module is prepended onto `Capybara`'s singleton class to route Capybara's global `session_pool` through `Experience::Pool`, unifying session management. Integrates with `capybara-screenshot` by setting `final_session_name`.
+
+**`Pool`** (`lib/capybara/experience/pool.rb`) — Singleton that extends `Hash`. Manages session lifecycle: `take` returns an idle session matching the driver+app or creates a new one; `reset_idle!` marks all sessions as reusable. Sessions are keyed as `"driver:object_id:app_object_id"`. The `[]` override auto-creates sessions on cache miss, which is how Capybara's `session_pool` integration works.
+
+**`BehaviorDSL`** (`lib/capybara/experience/rspec.rb`) — RSpec helper that provides `behavior` blocks for grouping steps within a single `it` block. Dynamically updates RSpec metadata so the test runner shows the current behavior name. Also registers an `after(:each)` hook on `type: :feature, js: true` tests to call `Pool#reset_idle!`.
+
+## Test Setup
+
+Tests use Capybara's built-in `TestApp` (Sinatra) as the rack app. A custom `:javascript_test` driver is registered as a RackTest driver to test driver-switching logic without requiring a real browser. The single feature spec covers pool allocation, session reuse across reset cycles, and driver switching.

data/Gemfile

@@ -2,3 +2,5 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in capybara-experience.gemspec
 gemspec
+
+gem "pry-byebug"

data/README.md

@@ -29,9 +29,51 @@ Or install it yourself as:
 
 ## Usage
 
-### Basic
+### Setup
+
+#### RSpec
+```ruby
+# spec/spec_helper.rb
+require "capybara/experience"
+require "capybara/experience/rspec"
+```
+
+This automatically includes `Capybara::Experience::DSL` and `BehaviorDSL` in feature specs.
+
+#### Minitest
+```ruby
+# test/test_helper.rb
+require "capybara/experience"
+require "capybara/experience/minitest"
+```
+
+Include the modules in your test class:
+```ruby
+class ApplicationIntegrationTest < Minitest::Test
+  include Capybara::DSL
+  include Capybara::Minitest::Assertions
+  include Capybara::Experience::MinitestHooks # includes DSL and resets pool after each test
+end
+```
+
+### Test Context & DSL
+
+Experience instances accept a test context as their first argument, enabling assertions to be called from within Experience subclasses. When you subclass `Capybara::Experience`, a factory method is automatically added to `Capybara::Experience::DSL` that passes `self` as the test context:
+
+```ruby
+class UserExperience < Capybara::Experience
+  # creates UserExperience() factory method on Capybara::Experience::DSL
+end
+
+# In a test:
+ux = UserExperience() # equivalent to UserExperience.new(self)
+```
+
+### Basic Example
+
 This scenario is for your standard user/admin.
-1. We need to create a file for each experience
+
+1. Create a file for each experience:
 
 ```ruby
 # spec/support/experiences/user_experience.rb
@@ -42,7 +84,8 @@ class UserExperience < Capybara::Experience
     @user = user
     login_as user, scope: :user
     visit '/'
-    assert_text "#{@user.name} Welcome!"
+    # assertions work inside Experience when test context is provided
+    expect(page).to have_content("#{@user.name} Welcome!")
     self
   end
 
@@ -53,17 +96,13 @@ end
 ```
 
 ```ruby
-# spec/support/experiences/user_experience.rb
+# spec/support/experiences/admin_experience.rb
 class AdminExperience < Capybara::Experience
-  def initialize(*args)
-    super
-  end
-
   def login(user)
     @user = user
     login_as user, scope: :admin
     visit '/admin/login'
-    assert_text "Home"
+    expect(page).to have_content("Home")
   end
 
   private
@@ -72,7 +111,7 @@ class AdminExperience < Capybara::Experience
 end
 ```
 
-2. now we need to create some capabilities. These capability files associate to each page, imagine each capability is an api to a page.
+2. Create some capabilities. These capability files associate to each page, imagine each capability is an api to a page.
 
 ```ruby
 # spec/support/capabilities/sign_up.rb
@@ -86,21 +125,19 @@ module Capabilities::SignUp
     fill_in "password", with: password
     fill_in "password_confirmation", with: password
     click_button "Submit"
-    assert_text "Welcome #{email}"
+    expect(page).to have_content("Welcome #{email}")
   end
 end
 ```
 
-3. write the spec
+3. Write the spec using the DSL factory methods:
+
 ```ruby
 # spec/features/sign_up_flow_spec.rb
-RSpec.describe "sign up flow", feature: true do
-  let(:guest_experience) { GuestExperience.new.extend(Capabilities::SignUp) }
-  let(:admin_experience) { AdminExperience.new.extend(Capabilities::Admin::ManageUser) }
-  
+RSpec.describe "sign up flow", type: :feature do
   it "works" do
-    behavior "user can sign up" do # behaviors are an added DSL by capybara-experiences to group interactions & assertions
-      guest_ux = GuestExperience.new
+    behavior "user can sign up" do
+      guest_ux = GuestExperience() # factory method passes self as test context
       guest_ux.navigate_to_sign_up
 
       guest_ux.sign_up(
@@ -112,9 +149,9 @@ RSpec.describe "sign up flow", feature: true do
     end
 
     behavior "admin can see user" do
-      admin_ux = AdminExperience.new
+      admin_ux = AdminExperience()
       admin_ux.login
-      admin_ux.to have_content "user@example.com"
+      expect(admin_ux).to have_content "user@example.com"
     end
   end
 end

data/capybara-experience.gemspec

@@ -28,6 +28,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "sinatra", ">= 3.0.2"
+  spec.add_development_dependency "minitest"
 
   spec.add_runtime_dependency "capybara", "~> 3.0"
 end

data/lib/capybara/experience/minitest.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+require "capybara/minitest"
+
+module Capybara
+  class Experience
+    module MinitestContext
+      Capybara::Minitest::Assertions.instance_methods(false).each do |method_name|
+        define_method(method_name) do |*args, **kwargs, &block|
+          test_context.send(method_name, page, *args, **kwargs, &block)
+        end
+      end
+    end
+
+    module MinitestBehaviorDSL
+      def behavior(name)
+        @_behavior_stack ||= []
+        @_behavior_stack.push(name)
+        yield
+      ensure
+        @_behavior_stack.pop
+      end
+
+      def current_behavior
+        @_behavior_stack ||= []
+        @_behavior_stack.join(" ")
+      end
+    end
+
+    module MinitestHooks
+      include Capybara::Experience::DSL
+      include Capybara::Experience::MinitestBehaviorDSL
+
+      def after_teardown
+        Capybara::Experience::Pool.instance.reset_idle!
+        super
+      end
+    end
+
+    include MinitestContext
+  end
+end

data/lib/capybara/experience/pool.rb

@@ -9,7 +9,7 @@ module Capybara
       def [](key)
         super(key) || begin
           driver, _session_name, app_object_id = key.split(":")
-          take(driver: driver, app_object_id: app_object_id, key: key)
+          take(driver: driver.to_sym, app_object_id: app_object_id.to_i, key: key)
         end
       end
 
@@ -27,6 +27,8 @@ module Capybara
         session
       end
 
+      attr_accessor :last_session
+
       def idle
         @idle ||= []
       end
@@ -36,10 +38,12 @@ module Capybara
       end
 
       def reset_idle!
-        to_h.each do |key, session|
-          self[session_key(session)] = delete(key)
+        new_hash = each_with_object({}) do |(key, session), hash|
+          hash[session_key(session)] = delete(key)
         end
+        replace(new_hash)
         @idle = values
+        @last_session = nil
 
         nil
       end

data/lib/capybara/experience/rails.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "capybara/experience"
+
+if defined?(RSpec)
+  require "capybara/experience/rspec"
+elsif defined?(Minitest)
+  require "capybara/experience/minitest"
+end
+
+module Capybara
+  class Experience
+    module ScreenshotOverride
+      def page
+        @_capybara_experience_page_override || super
+      end
+
+      private
+
+      def take_failed_screenshot
+        last_session = Experience::Pool.instance.last_session
+        return super unless last_session
+
+        @_capybara_experience_page_override = last_session
+        super
+      ensure
+        @_capybara_experience_page_override = nil
+      end
+    end
+  end
+end
+
+if defined?(ActiveSupport)
+  ActiveSupport.on_load(:action_dispatch_system_test_case) do
+    ActionDispatch::SystemTestCase.prepend(Capybara::Experience::ScreenshotOverride)
+  end
+end

data/lib/capybara/experience/rspec.rb

@@ -15,7 +15,9 @@ module Capybara
 
       def refresh_description
         metadata[:description] = metadata[:description_args].join(" ")
-        metadata[:full_description] = [metadata[:example_group][:full_description]].concat(metadata[:description_args]).join(" ")
+        metadata[:full_description] =
+          [metadata[:example_group][:full_description]]
+            .concat(metadata[:description_args]).join(" ")
       end
 
       def metadata
@@ -23,13 +25,28 @@ module Capybara
       end
 
       def in_continuous_integration_env?
-        ENV["CI"].present?
+        ENV["CI"]&.empty?
       end
     end
 
+    module RSpecContext
+      def expect(...)
+        test_context.expect(...)
+      end
+
+      Capybara::RSpecMatchers.instance_methods(false).each do |method_name|
+        define_method(method_name) do |*args, **kwargs, &block|
+          test_context.send(method_name, *args, **kwargs, &block)
+        end
+      end
+    end
+
+    include RSpecContext
+
     RSpec.configure do |config|
       config.include BehaviorDSL
-      config.prepend_after :each, type: :feature, js: true do
+      config.include Capybara::Experience::DSL, type: :feature
+      config.after :each, type: :feature, js: true do
         Capybara::Experience::Pool.instance.reset_idle!
       end
     end

data/lib/capybara/experience/version.rb

@@ -1,5 +1,5 @@
 module Capybara
   class Experience
-    VERSION = "0.3.3"
+    VERSION = "0.4.0"
   end
 end

data/lib/capybara/experience.rb

@@ -6,12 +6,19 @@ module Capybara
   class Experience
     include Capybara::DSL
 
-    delegate :t, to: I18n if defined?(I18n)
+    if defined?(I18n)
+      def t(*arg)
+        I18n.t(*args)
+      end
+    end
 
-    def initialize(driver_name: nil)
+    def initialize(test_context = nil, driver_name: nil)
+      @test_context = test_context
       @driver_name = driver_name
     end
 
+    attr_reader :test_context
+
     def reload_page
       visit current_url
     end
@@ -20,11 +27,14 @@ module Capybara
       @driver_name ||= Capybara.current_driver
     end
 
-    delegate :driver, to: :page
+    def driver
+      page.driver
+    end
 
     def page
       @page ||= Experience::Pool.instance.take(driver: driver_name)
 
+      Experience::Pool.instance.last_session = @page
       Capybara::Screenshot.final_session_name = @page.object_id if defined?(Capybara::Screenshot)
 
       @page
@@ -36,13 +46,27 @@ module Capybara
       end
     end
 
+    module DSL
+    end
+
+    def self.inherited(subclass)
+      super
+      return unless subclass.name
+
+      method_name = subclass.name.split("::").last
+      subclass_ref = subclass
+      DSL.define_method(method_name) do |**kwargs|
+        subclass_ref.new(self, **kwargs)
+      end
+    end
+
     class Error < StandardError; end
 
     module UnifySessionPool
       def page
-        Capybara::Screenshot.final_session_name = Capybara.session_name if defined?(Capybara::Screenshot)
-
-        super
+        Experience::Pool.instance.last_session = super.tap do
+          Capybara::Screenshot.final_session_name = Capybara.session_name if defined?(Capybara::Screenshot)
+        end
       end
 
       private

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara-experience
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Ryan Ong
 - Britt Lewis
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,6 +52,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.2
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +106,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CLAUDE.md
 - Gemfile
 - README.md
 - Rakefile
@@ -87,7 +115,9 @@ files:
 - capybara-experience.gemspec
 - lib/capybara-experience.rb
 - lib/capybara/experience.rb
+- lib/capybara/experience/minitest.rb
 - lib/capybara/experience/pool.rb
+- lib/capybara/experience/rails.rb
 - lib/capybara/experience/rspec.rb
 - lib/capybara/experience/version.rb
 homepage: https://github.com/ryanong/capybara-experience
@@ -95,7 +125,6 @@ licenses: []
 metadata:
   homepage_uri: https://github.com/ryanong/capybara-experience
   source_code_uri: https://github.com/ryanong/capybara-experience
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -110,8 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.17
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Simplify Capybara testing for larger applications
 test_files: []