capybara-presenter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 641d4e0c4f6f27c908eff20417912e7e98e8f610d95c0f448e0709fab2f93349
+  data.tar.gz: 8ed8c25c782cfdb7498a439a00ff88e3e0b402a395b54b38549b5bd600bf672f
+SHA512:
+  metadata.gz: 6b08f1f0be9dc7ac77b0b7773fbe730ab77308314177dba62e38b6ac1edf88b4c38bb54d936d9c90e0135ece22bfc4beecc547566dd9c1d648936d0e84c654ad
+  data.tar.gz: ac9b3f4e0d5a026faad59fc7f2528f55343860ed26f140a8660838fd680600e3de462341c28ac01618435a2970ba2847c8f8a2b4c6a0e2459c0c387910183c47

data/.rubocop.yml

@@ -0,0 +1,31 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  SuggestExtensions: false
+  NewCops: enable
+
+plugins:
+  - rubocop-minitest
+
+# Exclude test directories from metrics
+Metrics:
+  Exclude:
+    - 'test/**/*'
+    - 'examples/**/*'
+
+# Disable problematic cops
+Lint/MissingCopEnableDirective:
+  Enabled: false
+
+Lint/DuplicateBranch:
+  Enabled: false
+
+Naming/PredicateName:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# Allow multiple assertions in system tests
+Minitest/MultipleAssertions:
+  Exclude:
+    - 'examples/**/*'

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Input sanitization for JavaScript injection prevention in notifications
+- Environment variable validation with proper error handling and warnings
+- Comprehensive development infrastructure (CI, RuboCop, pre-commit hooks)
+- Support for presenter mode with visual notifications and delays
+- Automatic delays between Capybara actions for better presentations
+- Browser notifications for test milestones and progress
+- Configurable notification positions (top, center, bottom)
+- Sample application demonstrating gem functionality
+
+### Changed
+- Renamed gem from `capybara-demo` to `capybara-presenter` for clarity
+- Renamed API methods from `demo_*` to `presenter_*` for consistency
+- Renamed environment variables from `DEMO_*` to `PRESENTER_*`
+- Updated all documentation and examples to use presenter terminology
+- **BREAKING**: Raised minimum Ruby version from 3.1.0 to 3.2.0 for selenium-webdriver compatibility
+
+### Security
+- Added proper input sanitization to prevent XSS attacks in notifications
+- Implemented safe HTML and JavaScript escaping for user content
+
+### Development
+- Added GitHub Actions CI for Ruby 3.1, 3.2, and 3.3
+- Configured RuboCop with minimal overrides for code quality
+- Set up Lefthook for pre-commit hooks (RuboCop and tests)
+- Removed unused RSpec dependency in favor of Minitest
+- Added proper .gitignore for generated files
+
+## [0.1.0] - 2025-05-27
+
+### Added
+- Initial release of Capybara::Presenter gem
+- Basic presenter mode functionality
+- Configuration system with environment variable support
+- Integration with Capybara test framework
+- Documentation and examples

data/CLAUDE.md

@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common Development Commands
+
+### Testing
+- `rake test` - Run gem unit tests
+- `rake presenter:test` - Run sample app system tests
+- `bundle exec ruby test/test_capybara_demo.rb` - Run specific test file
+
+### Development Workflow
+- `bin/console` - Start IRB console with gem loaded
+- `bundle exec rubocop` - Run linting (enforced via pre-commit hooks)
+- `bundle exec rake install` - Install gem locally for testing
+- `bundle exec rake build` - Build gem package
+
+### Demo/Presentation Commands
+- `rake presenter:run` - Run live demo with browser automation
+- `rake presenter:browser` - Run browser-only demo
+- `rake presenter:help` - Show all available presenter options
+
+## Architecture Overview
+
+**Capybara::Presenter** is a Ruby gem that transforms standard Capybara system tests into presentation-ready demos. The gem operates by:
+
+1. **Environment-based activation**: Only active when `PRESENTER_MODE=true`
+2. **Zero overhead when disabled**: No performance impact in regular test runs
+3. **Visual feedback**: Displays notifications in browser during test execution
+4. **Configurable timing**: Adds delays between actions for recording-friendly pacing
+
+### Core Components
+
+- **Main module** (`lib/capybara/presenter.rb`): Entry point and configuration setup
+- **Configuration** (`lib/capybara/presenter/configuration.rb`): Global settings management
+- **Delays** (`lib/capybara/presenter/delays.rb`): Timing control between actions
+- **Notifications** (`lib/capybara/presenter/notifications.rb`): Browser notification system
+- **Capybara Extensions** (`lib/capybara/presenter/capybara_extensions.rb`): Monkey-patches Capybara methods
+
+### Key Patterns
+
+- **Method wrapping**: Core functionality wraps existing Capybara methods without breaking existing tests
+- **JavaScript injection**: Notifications are displayed via injected JavaScript in the browser
+- **Configuration precedence**: Environment variables override global configuration
+- **Sample app**: Complete working example in `examples/sample_app/` using Sinatra
+
+### Setup Requirements
+
+For full functionality, tests need:
+1. **Parallel testing disabled**: `parallelize(workers: 1)` when PRESENTER_MODE=true
+2. **Non-headless browser**: `driven_by :selenium, using: :chrome` for notifications
+3. **Test start notifications**: Call `presenter_test_start_notification(self.class, @NAME)` in setup
+4. **Automatic delays**: Call `setup_presenter_delays` in setup for action delays
+
+### Development Notes
+
+- **Ruby version**: Requires >= 3.2.0
+- **Dependencies**: Capybara >= 3.0, Selenium >= 4.0
+- **Testing**: Uses Minitest with comprehensive mocking for browser interactions
+- **Code quality**: RuboCop enforced via Lefthook pre-commit hooks

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 José Coelho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# Capybara::Presenter
+
+Transform your Capybara system tests into a presentations with automatic delays and browser notifications. Perfect for creating test recordings and demos.
+
+I had this in a project and it helps me give quick updates about the progress of a feature. I like to [communicate often](https://josecoelho.com/Software-Engineer/Communicate-often), the easier, the better. Decided to extract it to a gem with some help from Claude. I hope it's useful for you as well. :)
+
+![Demo](./examples/presenter.gif)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'capybara-presenter', group: :test
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Complete Setup
+
+**1. Include the module in your test class:**
+
+```ruby
+require 'capybara/presenter'
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  include Capybara::Presenter
+  
+  # Disable parallel testing in presenter mode for sequential execution
+  parallelize(workers: 1) if ENV["PRESENTER_MODE"] == "true"
+  
+  # Configure browser driver for presenter mode
+  if ENV["PRESENTER_MODE"] == "true"
+    driven_by :selenium, using: :chrome, screen_size: [1920, 1080]
+  else
+    driven_by :selenium, using: :headless_chrome
+  end
+  
+  # Add test start notifications and automatic delays
+  setup do
+    if presenter_mode?
+      presenter_test_start_notification(self.class, @NAME)
+      setup_presenter_delays
+    end
+  end
+end
+```
+
+**2. For Minitest users, also add to your individual test classes:**
+
+```ruby
+class UsersSystemTest < ApplicationSystemTestCase
+  # Test methods automatically get start notifications
+end
+```
+
+**3. For RSpec users:**
+
+```ruby
+RSpec.configure do |config|
+  config.include Capybara::Presenter, type: :system
+  
+  config.before(:each, type: :system) do
+    if presenter_mode?
+      presenter_test_start_notification(self.class, example.description)
+      setup_presenter_delays
+    end
+  end
+end
+```
+
+### Running Tests in Presenter Mode
+
+```bash
+# Enable presenter mode
+PRESENTER_MODE=true bundle exec rails test:system
+
+# Customize timing
+PRESENTER_MODE=true PRESENTER_DELAY=1.5 bundle exec rails test:system
+
+# Disable notifications
+PRESENTER_MODE=true PRESENTER_NOTIFICATIONS=false bundle exec rails test:system
+```
+
+### In Your Tests
+
+```ruby
+test "user registration" do
+  visit new_user_registration_path
+  
+  fill_in "Email", with: "user@example.com"
+  fill_in "Password", with: "password123"
+  presenter_milestone("Form Complete", "All fields filled")
+  
+  click_button "Sign up"
+  presenter_milestone("Success", "User registered successfully")
+  
+  assert_text "Welcome!"
+end
+```
+
+## API
+
+- `presenter_mode?` - Check if presenter mode is enabled
+- `presenter_delay(seconds)` - Add custom delay
+- `presenter_notification(title, message)` - Show browser notification
+- `presenter_milestone(title, message)` - Show milestone notification
+
+## Configuration
+
+```ruby
+Capybara::Presenter.configure do |config|
+  config.enabled = ENV['PRESENTER_MODE'] == 'true'
+  config.delay = 2.0
+  config.notifications = true
+  config.notification_position = :center  # :top, :center, :bottom
+end
+```
+
+## Environment Variables
+
+- `PRESENTER_MODE=true` - Enable presenter mode
+- `PRESENTER_DELAY=2.0` - Action delay in seconds
+- `PRESENTER_TEST_START_DELAY=2.0` - Delay before each test
+- `PRESENTER_NOTIFICATIONS=false` - Disable notifications
+
+## Browser Setup
+
+For notifications to appear, use a non-headless driver:
+
+```ruby
+if ENV["PRESENTER_MODE"] == "true"
+  driven_by :selenium, using: :chrome
+else
+  driven_by :selenium, using: :headless_chrome
+end
+```
+
+## Examples
+
+```bash
+# See the gem in action
+rake presenter:run
+
+# View all options
+rake presenter:help
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+# Main gem tests
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/test_*.rb']
+end
+
+# Presenter and example tasks
+# rubocop:disable Metrics/BlockLength
+namespace :presenter do
+  desc 'Run the sample app system tests in normal mode'
+  task :test do
+    Dir.chdir('examples/sample_app') do
+      sh 'ruby system_test.rb'
+    end
+  end
+
+  desc 'Run the sample app system tests in presenter mode'
+  task :run do
+    Dir.chdir('examples/sample_app') do
+      sh 'PRESENTER_MODE=true ruby system_test.rb'
+    end
+  end
+
+  desc 'Run presenter with custom delays (DELAY=3.0 START_DELAY=2.0)'
+  task :slow do
+    delay = ENV['DELAY'] || '3.0'
+    start_delay = ENV['START_DELAY'] || '2.0'
+    Dir.chdir('examples/sample_app') do
+      sh "PRESENTER_MODE=true PRESENTER_DELAY=#{delay} PRESENTER_TEST_START_DELAY=#{start_delay} ruby system_test.rb"
+    end
+  end
+
+  desc 'Show all presenter options'
+  task :help do
+    puts <<~HELP
+      🎬 Capybara::Presenter - Available Rake Tasks
+
+      Main Tasks:
+        rake test               - Run gem unit tests
+        rake presenter:test     - Run sample app tests (normal mode)
+        rake presenter:run      - Run sample app tests (presenter mode)
+        rake presenter:slow     - Run presenter with slower timing
+
+      Custom Presenter Options:
+        rake presenter:slow DELAY=3.0 START_DELAY=2.0
+      #{'  '}
+      Environment Variables:
+        PRESENTER_MODE=true              - Enable presenter mode
+        PRESENTER_DELAY=2.0              - Action delay in seconds
+        PRESENTER_TEST_START_DELAY=2.0   - Test start delay in seconds
+        PRESENTER_NOTIFICATIONS=false    - Disable notifications
+      #{'  '}
+      Examples:
+        rake presenter:run                                  # Basic presenter
+        PRESENTER_DELAY=1.0 rake presenter:run            # Faster presenter
+        PRESENTER_NOTIFICATIONS=false rake presenter:run  # No notifications
+    HELP
+  end
+end
+# rubocop:enable Metrics/BlockLength
+
+task default: :test
+
+# Add help task at top level
+desc 'Show all available tasks'
+task :help do
+  puts <<~HELP
+    🎬 Capybara::Presenter Gem
+
+    Main Commands:
+      rake test              - Run gem tests
+      rake presenter:help    - Presenter options
+    #{'  '}
+    Quick Start:
+      rake presenter:run     - See the gem in action!
+  HELP
+end

data/lefthook.yml

@@ -0,0 +1,8 @@
+pre-commit:
+  commands:
+    rubocop:
+      run: bundle exec rubocop --autocorrect {staged_files}
+      glob: "*.rb"
+      stage_fixed: true
+    tests:
+      run: bundle exec rake test

data/lib/capybara/presenter/capybara_extensions.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Presenter
+    # Extends Capybara methods with presentation features.
+    # Wraps common Capybara actions to add delays and logging for better presentations.
+    module CapybaraExtensions
+      WRAPPED_METHODS = %i[visit click_button click_link click_on fill_in select choose check uncheck
+                           attach_file].freeze
+
+      # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def setup_presenter_delays
+        return unless presenter_mode?
+        return if self.class.instance_variable_get(:@presenter_delays_setup)
+
+        self.class.instance_variable_set(:@presenter_delays_setup, true)
+
+        WRAPPED_METHODS.each do |action|
+          next if respond_to?(:"#{action}_without_presenter")
+
+          # Create alias for original method
+          self.class.alias_method :"#{action}_without_presenter", action
+
+          # Override the method with presenter delays
+          self.class.define_method(action) do |*args, **kwargs, &block|
+            if presenter_mode?
+              log_presenter_action(action, args.first)
+
+              # Pre-action delay
+              case action
+              when :click_button, :click_link, :click_on
+                presenter_delay(0.3)
+              when :fill_in, :select, :choose, :check, :uncheck
+                presenter_delay(0.2)
+              when :visit
+                presenter_delay(0.5)
+              when :attach_file
+                presenter_delay(0.3)
+              end
+            end
+
+            # Execute the original action
+            result = send(:"#{action}_without_presenter", *args, **kwargs, &block)
+
+            # Post-action delay for actions that trigger page changes
+            presenter_delay(0.8) if presenter_mode? && %i[click_button click_link click_on visit].include?(action)
+
+            result
+          end
+        end
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      private
+
+      # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def log_presenter_action(action, target)
+        return unless presenter_mode?
+
+        case action
+        when :click_button, :click_link, :click_on
+          puts "🖱️  Clicking: #{target}" if target
+        when :fill_in
+          puts "⌨️  Filling: #{target}" if target
+        when :select, :choose, :check, :uncheck
+          puts "☑️  Selecting: #{target}" if target
+        when :visit
+          puts "🌐 Navigating to: #{target}" if target
+        when :attach_file
+          puts "📎 Attaching file: #{target}" if target
+        end
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    end
+  end
+end

data/lib/capybara/presenter/configuration.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Presenter
+    # Configuration class for Capybara::Presenter settings.
+    # Manages global settings like delays, notifications, and environment variable parsing.
+    class Configuration
+      attr_reader :enabled, :delay, :notifications, :notification_position, :test_start_delay
+
+      def initialize
+        @enabled = ENV['PRESENTER_MODE'] == 'true'
+        @delay = parse_float_env('PRESENTER_DELAY', 2.0)
+        @notifications = ENV['PRESENTER_NOTIFICATIONS'] != 'false'
+        @notification_position = :center
+        @test_start_delay = parse_float_env('PRESENTER_TEST_START_DELAY', 2.0)
+      end
+
+      def enabled=(value)
+        @enabled = !!value
+      end
+
+      def delay=(value)
+        raise ArgumentError, 'delay must be a positive number' unless value.is_a?(Numeric) && value.positive?
+
+        @delay = value.to_f
+      end
+
+      def notifications=(value)
+        @notifications = !!value
+      end
+
+      def notification_position=(value)
+        valid_positions = %i[top center bottom]
+        unless valid_positions.include?(value)
+          raise ArgumentError, "notification_position must be one of: #{valid_positions.join(', ')}"
+        end
+
+        @notification_position = value
+      end
+
+      def test_start_delay=(value)
+        raise ArgumentError, 'test_start_delay must be a positive number' unless value.is_a?(Numeric) && value >= 0
+
+        @test_start_delay = value.to_f
+      end
+
+      private
+
+      # rubocop:disable Metrics/MethodLength
+      def parse_float_env(env_var, default)
+        value = ENV.fetch(env_var, nil)
+        return default unless value
+
+        begin
+          parsed = Float(value)
+          if parsed.negative?
+            warn "Warning: #{env_var}=#{value} is negative, using default #{default}"
+            default
+          else
+            parsed
+          end
+        rescue ArgumentError
+          warn "Warning: #{env_var}=#{value} is not a valid number, using default #{default}"
+          default
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+    end
+  end
+end

data/lib/capybara/presenter/notifications.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Presenter
+    # Provides browser notification functionality for presenting test milestones.
+    # Injects JavaScript to display visual notifications during test execution.
+    # rubocop:disable Metrics/ModuleLength
+    module Notifications
+      def presenter_notification(title, message = nil, type: :info, duration: 4000)
+        return unless presenter_mode? && presenter_notifications_enabled?
+
+        show_browser_notification(title, message, type, duration)
+      end
+
+      def presenter_milestone(title, message = nil)
+        return unless presenter_mode?
+
+        presenter_notification("📋 #{title}", message, type: :success, duration: 3000)
+        presenter_delay(1.0)
+      end
+
+      def presenter_test_start_notification(test_class, test_method)
+        return unless presenter_mode? && presenter_notifications_enabled?
+
+        test_name = test_class.name.gsub(/Test$/, '')
+        method_name = test_method.gsub(/^test_/, '').gsub('_', ' ').split.map(&:capitalize).join(' ')
+
+        presenter_notification("🧪 #{test_name}", "Running: #{method_name}", type: :info, duration: 8000)
+        puts "📋 Starting test: #{test_name} - #{method_name}"
+        presenter_delay(Capybara::Presenter.configuration.test_start_delay)
+      end
+
+      private
+
+      def show_browser_notification(title, message, type, duration)
+        return unless has_browser_access?
+
+        begin
+          page.driver.browser.execute_script(notification_javascript(title, message, type, duration))
+        rescue StandardError => e
+          # Gracefully handle JavaScript errors
+          puts "Presenter notification failed: #{e.message}" if ENV['DEBUG']
+        end
+      end
+
+      def has_browser_access?
+        respond_to?(:page) &&
+          page.respond_to?(:driver) &&
+          page.driver.respond_to?(:browser)
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def notification_javascript(title, message, _type, duration)
+        # Sanitize inputs to prevent XSS
+        safe_title = sanitize_for_js(title)
+        safe_message = sanitize_for_js(message) if message
+        safe_title_html = sanitize_for_html(title)
+        safe_message_html = sanitize_for_html(message) if message
+
+        position = notification_position_css
+        <<~JS
+          console.log('Presenter notification: #{safe_title}');
+
+          // Remove existing presenter notifications
+          document.querySelectorAll('.presenter-notification').forEach(el => el.remove());
+
+          // Create notification container if it doesn't exist
+          let container = document.getElementById('presenter-notification-container');
+          if (!container) {
+            container = document.createElement('div');
+            container.id = 'presenter-notification-container';
+            container.style.cssText = `
+              position: fixed;
+              #{position}
+              z-index: 10000;
+              pointer-events: none;
+              display: flex;
+              flex-direction: column;
+              align-items: center;
+              gap: 12px;
+            `;
+            document.body.appendChild(container);
+          }
+
+          // Create notification element
+          const notification = document.createElement('div');
+          notification.className = 'presenter-notification';
+
+          notification.style.cssText = `
+            background: rgba(0, 0, 0, 0.5);
+            color: white;
+            padding: 32px 48px;
+            border-radius: 8px;
+            min-width: 700px;
+            max-width: 900px;
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            font-size: 22px;
+            font-weight: 600;
+            line-height: 1.3;
+            text-align: center;
+            transition: all 0.3s ease-in-out;
+            pointer-events: auto;
+          `;
+
+          notification.innerHTML = `
+            <div style="font-size: 26px; font-weight: 800; margin-bottom: #{message ? '12px' : '0'};">#{safe_title_html}</div>
+            #{safe_message ? "<div style=\"font-size: 20px; font-weight: 500; opacity: 0.9;\">#{safe_message_html}</div>" : ''}
+          `;
+
+          container.appendChild(notification);
+
+          // Auto remove after duration
+          setTimeout(() => {
+            notification.style.opacity = '0';
+            notification.style.transform = 'translateY(-10px)';
+            setTimeout(() => {
+              if (notification.parentNode) {
+                notification.parentNode.removeChild(notification);
+              }
+            }, 300);
+          }, #{duration});
+
+          // Click to dismiss
+          notification.addEventListener('click', () => {
+            notification.style.opacity = '0';
+            notification.style.transform = 'translateY(-10px)';
+            setTimeout(() => {
+              if (notification.parentNode) {
+                notification.parentNode.removeChild(notification);
+              }
+            }, 300);
+          });
+        JS
+      end
+
+      def notification_position_css
+        case Capybara::Presenter.configuration.notification_position
+        when :top
+          'top: 40px; left: 50%; transform: translateX(-50%);'
+        when :center
+          'top: 50%; left: 50%; transform: translate(-50%, -50%);'
+        when :bottom
+          'bottom: 40px; left: 50%; transform: translateX(-50%);'
+        else
+          'top: 40px; left: 50%; transform: translateX(-50%);'
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def sanitize_for_js(string)
+        return '' unless string
+
+        string.to_s
+              .gsub('\\', '\\\\')   # Escape backslashes first
+              .gsub("'", "\\'")     # Escape single quotes
+              .gsub('"', '\\"')     # Escape double quotes
+              .gsub("\n", '\\n')    # Escape newlines
+              .gsub("\r", '\\r')    # Escape carriage returns
+              .gsub("\t", '\\t')    # Escape tabs
+              .gsub('</script>', '<\\/script>') # Prevent script injection
+      end
+
+      def sanitize_for_html(string)
+        return '' unless string
+
+        string.to_s
+              .gsub('&', '&amp;')   # Escape ampersands first
+              .gsub('<', '&lt;')    # Escape less than
+              .gsub('>', '&gt;')    # Escape greater than
+              .gsub('"', '&quot;')  # Escape double quotes
+              .gsub("'", '&#39;')   # Escape single quotes
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/capybara/presenter/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Presenter
+    VERSION = '0.1.0'
+  end
+end

data/lib/capybara/presenter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative 'presenter/version'
+require_relative 'presenter/configuration'
+require_relative 'presenter/notifications'
+require_relative 'presenter/capybara_extensions'
+
+module Capybara
+  # Main module for the Capybara::Presenter gem.
+  # Transforms standard Capybara system tests into presentation-ready demos
+  # with visual notifications and configurable delays.
+  module Presenter
+    class Error < StandardError; end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration) if block_given?
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+
+      # Show setup guidance when presenter mode is enabled
+      return unless configuration.enabled
+
+      show_setup_guidance
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    def self.show_setup_guidance
+      puts <<~GUIDANCE
+
+        🎬 Capybara::Presenter Setup Guidance:
+
+        For browser notifications to appear:
+        1. Use a non-headless driver (Chrome, Firefox, Safari)
+        2. Ensure browser opens visibly#{' '}
+        3. Disable parallel testing: parallelize(workers: 1)
+
+        Environment variables:
+        - PRESENTER_DELAY=2.0 (action delays)
+        - PRESENTER_TEST_START_DELAY=2.0 (pause before each test)
+        - PRESENTER_NOTIFICATIONS=false (disable notifications)
+
+        💡 This gem works with your existing Capybara driver configuration
+
+      GUIDANCE
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # Class-level helper methods for checking presenter configuration.
+    module ClassMethods
+      def presenter_mode?
+        Capybara::Presenter.configuration.enabled
+      end
+
+      def presenter_delay_duration
+        Capybara::Presenter.configuration.delay
+      end
+
+      def presenter_notifications_enabled?
+        Capybara::Presenter.configuration.notifications
+      end
+    end
+
+    # Instance-level helper methods for checking presenter configuration.
+    module InstanceMethods
+      include Notifications
+      include CapybaraExtensions
+
+      def presenter_mode?
+        self.class.presenter_mode?
+      end
+
+      def presenter_delay(seconds = nil)
+        return unless presenter_mode?
+
+        sleep(seconds || presenter_delay_duration)
+      end
+
+      def presenter_delay_duration
+        self.class.presenter_delay_duration
+      end
+
+      def presenter_notifications_enabled?
+        self.class.presenter_notifications_enabled?
+      end
+    end
+  end
+end

data/sig/capybara/demo.rbs

@@ -0,0 +1,70 @@
+module Capybara
+  module Presenter
+    VERSION: String
+
+    class Configuration
+      attr_reader enabled: bool
+      attr_reader delay: Float
+      attr_reader notifications: bool
+      attr_reader notification_position: Symbol
+      attr_reader notification_style: Symbol
+      attr_reader test_start_delay: Float
+
+      def initialize: () -> void
+      def enabled=: (untyped value) -> bool
+      def delay=: (Numeric value) -> Float
+      def notifications=: (untyped value) -> bool
+      def notification_position=: (Symbol value) -> Symbol
+      def notification_style=: (Symbol value) -> Symbol
+      def test_start_delay=: (Numeric value) -> Float
+
+      private
+
+      def parse_float_env: (String env_var, Float default) -> Float
+    end
+
+    module Notifications
+      def presenter_notification: (String title, ?String? message, ?type: Symbol, ?duration: Integer) -> void
+      def presenter_milestone: (String title, ?String? message) -> void
+      def presenter_test_start_notification: (Class test_class, String test_method) -> void
+
+      private
+
+      def show_browser_notification: (String title, String? message, Symbol type, Integer duration) -> void
+      def has_browser_access?: () -> bool
+      def notification_javascript: (String title, String? message, Symbol type, Integer duration) -> String
+      def notification_position_css: () -> String
+      def sanitize_for_js: (String? string) -> String
+      def sanitize_for_html: (String? string) -> String
+    end
+
+    module Delays
+      def presenter_delay: (?Float? seconds) -> void
+    end
+
+    module CapybaraExtensions
+      def setup_presenter_delays: () -> void
+
+      private
+
+      def log_presenter_action: (Symbol action, untyped target) -> void
+    end
+
+    def self.configuration: () -> Configuration
+    def self.configure: () { (Configuration) -> void } -> void
+    def self.reset_configuration!: () -> Configuration
+    def self.show_setup_guidance: () -> void
+
+    module ClassMethods
+      def presenter_mode?: () -> bool
+      def presenter_delay_duration: () -> Float
+      def presenter_notifications_enabled?: () -> bool
+    end
+
+    module InstanceMethods
+      def presenter_mode?: () -> bool
+      def presenter_delay_duration: () -> Float
+      def presenter_notifications_enabled?: () -> bool
+    end
+  end
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: capybara-presenter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- José Coelho
+bindir: exe
+cert_chain: []
+date: 2025-05-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: lefthook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.38'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.38'
+description: Transform Capybara system tests into polished presentations with automatic
+  delays, browser notifications, and visual cues perfect for creating professional
+  test recordings and demonstrations.
+email:
+- jose.coelho@palomagroup.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lefthook.yml
+- lib/capybara/presenter.rb
+- lib/capybara/presenter/capybara_extensions.rb
+- lib/capybara/presenter/configuration.rb
+- lib/capybara/presenter/notifications.rb
+- lib/capybara/presenter/version.rb
+- sig/capybara/demo.rbs
+homepage: https://github.com/josecoelho/capybara-presenter
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/josecoelho/capybara-presenter
+  source_code_uri: https://github.com/josecoelho/capybara-presenter
+  changelog_uri: https://github.com/josecoelho/capybara-presenter/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.6
+specification_version: 4
+summary: Make Capybara tests presentation-ready with visual notifications and recording-friendly
+  delays
+test_files: []