integration-tests-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30f959f27b2ebdf182bc6a8107f851baeb5f77805e02bfff5bf2dc591faecb5c
+  data.tar.gz: 4b5dbdb852a9aecef5346044bf3b6ddb2f3349fa92e62411d39af6bd6c8a1b05
+SHA512:
+  metadata.gz: f52d395e2dd5ab6fe1726e050f28c9dd34b8153a6d6e7b45dabd61ac15b0a1bac9f5aa15d49e1bc5247d0a2c42e84b9ee9ec0c98bb831ec6a535d526a77c5cb0
+  data.tar.gz: f370d6841dfc1a179f8cf20aee07ff137f6f38f45eceeabb1838e0a5cde9902d9d04c5df8b7e5e498ce5c9fdb43d3db1de03f27bb5069359bc5d46f099fc614c

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025
+
+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,211 @@
+# Integration Tests Rails
+
+This gem is designed to facilitate integration testing in Ruby on Rails applications. It provides a streamlined way to configure and run integration tests while capturing coverage data for JavaScript files.
+
+## Tech Stack
+
+- **Ruby on Rails** - The primary framework for building web applications.
+- **RSpec** - A testing tool for Ruby, used for writing and executing test cases.
+- **Capybara** - A library that helps you test web applications by simulating how a real user would interact with your app.
+- **Cuprite** - A Capybara driver that uses Chrome DevTools Protocol.
+- **Istanbul** - A JavaScript code coverage tool.
+- **Puma** - A concurrent web server.
+
+## Getting Started
+
+### Installation
+
+Add this line to your Rails application's Gemfile:
+
+```ruby
+group :development, :test do
+  gem 'integration_tests_rails', require: false
+end
+```
+
+Test environment is needed to run integration tests. Development environment is needed to be able to use terminal commands provided by the gem.
+
+After adding the gem, run the following command to install it:
+
+```sh
+bundle install
+```
+
+After installation, run:
+
+```sh
+rails generate integration_tests_rails:install
+```
+
+If you do not have `Yarn` installed, the above command will prompt you to install it. Follow the instructions to complete the installation. Re-run the command after installing `Yarn`.
+
+The generator will do the following:
+- Install Instanbul using Yarn.
+- Create a controller that can be used to *unit test JavaScript code*.
+- Add a line in `routes.rb` to route requests to the above controller.
+- Add an entry in `.gitignore` to ignore coverage reports and locally installed Istanbul packages.
+
+### Configuration
+
+Since test suites can vary greatly between applications, manual setup of the configuration may vary. It is recommended to create a separate helper file alongside `spec_helper.rb` and `rails_helper.rb`.
+
+```ruby
+# spec/capybara_helper.rb
+
+require 'integration_tests_rails'
+
+IntegrationTestsRails.setup
+
+require_relative 'features/tests_controller' # Loads the controller for unit testing JavaScript.
+```
+
+The `IntegrationTestsRails.setup` method accepts an optional block for further customization. Below is an example how to use and contains the default values:
+
+```ruby
+IntegrationTestsRails.setup do |config|
+  config.chrome_url = nil # Used for remote Chrome instances. Needs remote to be true.
+  config.max_server_retries = 1000 # Before running the tests, Cuprite starts a server to communicate with Chrome. This sets the maximum number of retries to connect to that server.
+  config.puma_threads = '1:1' # Number of threads for the Puma server used by Cuprite.
+  config.remote = false # Whether to use a remote Chrome instance.
+  config.server_host = '0.0.0.0' # Host for the Puma server used by Cuprite.
+  config.server_port = nil # Port for the Puma server used by Cuprite.
+  config.source_dir = 'app/javascript' # Directory containing the JavaScript files to be instrumented.
+  config.verbose = false # Whether to enable verbose logging.
+  config.wait_time = 5 # Max time in seconds to wait after each request by Capybara to load content.
+  config.window_size = [1920, 1080] # Size of the browser window used by Cuprite.
+end
+```
+
+## Unit Testing JavaScript Code
+
+### Usage
+
+To unit test JavaScript code, the provided `TestsController (spec/support/features/tests_controller)` can be modified. By default, it only renders a complete HTML page that also loads importmap-supporting JavaScript code to set up the environment for testing.
+
+```ruby
+class TestsController < ActionController::Base
+  def index
+    render inline: <<~HTML.squish
+      <!DOCTYPE html>
+      <html lang="en">
+        <head>
+          <meta charset="UTF-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <meta name="turbo-visit-control" content="reload">
+          <%%= csrf_meta_tags %>
+          <%%= csp_meta_tag %>
+          <%%= stylesheet_link_tag :app, "data-turbo-track": "reload" %>
+          <%%= stylesheet_link_tag 'custom', "data-turbo-track": "reload" %>
+          <%%= javascript_importmap_tags %>
+        </head>
+        <body>
+        </body>
+      </html>
+    HTML
+  end
+end
+```
+
+Since vendored JavaScript are not included by default, additional tags may be required to load them. For example, if there exists a `custom_code.js` file in `app/javascript`:
+
+```ruby
+<<~HTML.squish
+  <!DOCTYPE html>
+  <html lang="en">
+    <head>
+      <meta charset="UTF-8">
+      <meta name="viewport" content="width=device-width, initial-scale=1.0">
+      <meta name="turbo-visit-control" content="reload">
+      <%%= csrf_meta_tags %>
+      <%%= csp_meta_tag %>
+      <%%= stylesheet_link_tag :app, "data-turbo-track": "reload" %>
+      <%%= stylesheet_link_tag 'custom', "data-turbo-track": "reload" %>
+      <%%= javascript_importmap_tags %>
+
+      <script type="module">
+        import CustomCode from 'custom_code';
+        window.CustomCode = CustomCode;
+      </script>
+    </head>
+    <body>
+    </body>
+  </html>
+HTML
+```
+
+### Writing Tests
+
+Tests can be written using RSpec and Capybara as follows:
+
+```ruby
+require 'capybara_helper'
+
+RSpec.describe 'Custom Code Unit Test', type: :feature, unit: true do
+  describe '#doSomething' do
+    let(:script) do
+      'CustomCode.doSomething();'
+    end
+
+    it 'does something' do
+      expect(result).to eq('Did something!')
+    end
+  end
+end
+```
+
+The `script` component is the JavaScript code that will be executed for the test. The `result` component will contain the return value of the evaluated script. The `script` can accept string or heredoc formats:
+
+```ruby
+let(:script) do
+  <<~JS
+    CustomCode.doSomething();
+  JS
+end
+```
+
+Do note that **the `script` component can execute one statement only**. If multiple statements are needed, consider wrapping them in a function and invoking that function in the `script` component.
+
+```ruby
+let(:script) do
+  <<~JS
+    (() => {
+      const value1 = CustomCode.getValue1();
+      const value2 = CustomCode.getValue2();
+      return CustomCode.combineValues(value1, value2);
+    })();
+  JS
+end
+```
+
+The above will successfully execute the three statements and return the value in `result`. However, this can become a problem if the JavaScript code being tested relies on waiting for each statement to complete. In such cases, it is recommended to use an array instead in `script`:
+
+```ruby
+let(:script) do
+  [
+    <<~JS,
+      CustomCode.initialize();
+      CustomCode.doSomething();
+    JS
+    'CustomCode.openModal()',
+    'CustomCode.closeModal()'
+  ]
+end
+```
+
+In such cases where `script` is an array, the `result` component will contain the return value of the **last statement only**.
+
+
+## Integration Testing
+
+Refer to [Cuprite](https://github.com/rubycdp/cuprite) and [Capybara](https://github.com/teamcapybara/capybara). Use them as normally in integration tests.
+
+## JavaScript Coverage Reports
+
+After the tests (successful, failed or cancelled), coverage reports will be generated in `coverage/javascript` by default.
+
+## Contributing
+
+1. Fork the repository.
+2. Create a new branch for your feature or bugfix.
+3. Make your changes.
+5. Submit a pull request describing your changes.

data/lib/generators/integration_tests_rails/install_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module IntegrationTestsRails
+  module Generators
+    # Generator responsible for setting up the Rails project with necessary tools to make integration testing possible.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Initialize project for integration testing.'
+
+      def install_node_dependencies
+        unless system('which yarn > /dev/null 2>&1')
+          say 'Yarn is not installed. Please install Yarn first: https://yarnpkg.com/getting-started/install', :red
+          exit 1
+        end
+
+        say 'Installing Istanbul...', :green
+        run 'yarn add --dev istanbul-lib-instrument istanbul-lib-coverage istanbul-lib-report istanbul-reports'
+        run 'yarn install'
+      end
+
+      def copy_tests_controller
+        template 'tests_controller.rb', 'spec/support/features/tests_controller.rb'
+      end
+
+      def add_route
+        route 'resources(:tests, only: :index) if Rails.env.test?'
+      end
+
+      def update_gitignore
+        gitignore_path = '.gitignore'
+        lines_to_add = ['node_modules/', 'coverage/']
+
+        return unless File.exist?(gitignore_path)
+
+        content = File.read(gitignore_path)
+        lines_to_add.each do |line|
+          if content.include?(line)
+            say "'#{line}' already exists in .gitignore", :blue
+          else
+            append_to_file gitignore_path, "\n#{line}\n"
+            say "Added '#{line}' to .gitignore", :green
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/integration_tests_rails/templates/tests_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# This provides a minimal page that loads your JavaScript
+class TestsController < ActionController::Base
+  def index
+    render inline: <<~HTML.squish
+      <!DOCTYPE html>
+      <html lang="en">
+        <head>
+          <meta charset="UTF-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <meta name="turbo-visit-control" content="reload">
+          <%%= csrf_meta_tags %>
+          <%%= csp_meta_tag %>
+          <%%= stylesheet_link_tag :app, "data-turbo-track": "reload" %>
+          <%%= stylesheet_link_tag 'custom', "data-turbo-track": "reload" %>
+          <%%= javascript_importmap_tags %>
+          <!-- If there are JavaScript libraries not globally available, include them here for testing.-->
+          <!-- E.g. The block below shows how to import a JavaScript module and attach it to the window object. -->
+          <!-- The file is located in app/javascripts/libs/my_library.js -->
+          <!--
+          <script type="module">
+            import MyLibrary from 'libs/my_library';
+            window.MyLibrary = MyLibrary;
+          </script>
+          -->
+        </head>
+        <body>
+          <!-- Include JavaScript libraries here instead if they need to be loaded much later. -->
+          <!-- E.g. The line below loads a JavaScript file located in app/assets/javascripts/plugins/vendor.min.js -->
+          <%%#= javascript_include_tag 'plugins/vendor.min' %>
+        </body>
+      </html>
+    HTML
+  end
+end

data/lib/integration_tests_rails/capybara/helpers.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module IntegrationTestsRails
+  module Capybara
+    # Adds helpers to enable unit testing.
+    module Helper
+      extend RSpec::SharedContext
+
+      let(:result) do
+        case script
+        when Array
+          script.map { |cmd| page.evaluate_script(cmd) }.last
+        when String
+          page.evaluate_script(script)
+        end
+      end
+
+      let(:script) { nil }
+
+      before do
+        visit tests_path
+        result
+      end
+    end
+  end
+end

data/lib/integration_tests_rails/capybara/local.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module IntegrationTestsRails
+  module Capybara
+    # Configure Capybara to use local Chrome browser via Cuprite.
+    module Local
+      class << self
+        def setup
+          config = IntegrationTestsRails.configuration
+
+          ::Capybara.default_max_wait_time = config.wait_time
+          ::Capybara.server = :puma, { Silent: !Util.verbose? }
+
+          register_driver
+          Util.log 'Local Chrome Mode: Server is running locally'
+        end
+
+        private
+
+        def register_driver
+          config = IntegrationTestsRails.configuration
+
+          ::Capybara.register_driver(:cuprite) do |app|
+            options = {
+              window_size: config.window_size,
+              browser_options: {
+                'no-sandbox' => nil,
+                'disable-dev-shm-usage' => nil,
+                'disable-web-security' => nil,
+                'disable-gpu' => nil
+              }
+            }
+
+            Util.log 'Registered Cuprite driver using local configuration'
+            ::Capybara::Cuprite::Driver.new(app, options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/integration_tests_rails/capybara/remote.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module IntegrationTestsRails
+  module Capybara
+    # Configure Capybara to use remote Chrome browser via Cuprite.
+    module Remote
+      class << self
+        def setup
+          config = IntegrationTestsRails.configuration
+          server_host = config.server_host
+          server_port = config.server_port
+
+          ::Capybara.server_host = server_host
+          ::Capybara.server_port = server_port
+          ::Capybara.default_max_wait_time = config.wait_time
+          ::Capybara.app_host = "http://localhost:#{server_port}"
+          ::Capybara.server = :puma, {
+            Silent: !Util.verbose?,
+            Host: server_host,
+            Port: server_port,
+            Threads: config.puma_threads
+          }
+
+          register_driver
+          Util.log "Remote Chrome Mode: Test server bound to #{server_host}:#{server_port}"
+        end
+
+        private
+
+        def register_driver
+          config = IntegrationTestsRails.configuration
+
+          ::Capybara.register_driver(:cuprite) do |app|
+            timeout = config.timeout
+            options = {
+              window_size: config.window_size,
+              url: config.chrome_url,
+              timeout: timeout,
+              process_timeout: timeout
+            }
+
+            Util.log 'Registered Cuprite driver using remote configuration'
+            ::Capybara::Cuprite::Driver.new(app, options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/integration_tests_rails/capybara/util.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'helpers'
+
+module IntegrationTestsRails
+  module Capybara
+    # Utilities for Capybara setup and configuration are found here.
+    module Util
+      class << self
+        def configure_webmock
+          WebMock.disable_net_connect!(allow_localhost: true)
+          log 'WebMock configured to allow localhost connections'
+        end
+
+        def ensure_server_ready(context)
+          return if @server_ready
+
+          config = IntegrationTestsRails.configuration
+          log "Waiting for server on #{::Capybara.app_host.presence || 'localhost'} to start..."
+
+          server_retries = config.max_server_retries
+          server_retries.times do |attempt|
+            context.visit('/400')
+            @server_ready = true
+            log 'Server is ready!'
+            break
+          rescue StandardError
+            log "Server not ready (attempt #{attempt + 1}/#{server_retries})."
+          end
+          log "Server did not start after #{server_retries} attempts..." unless @server_ready
+        end
+
+        def configure_rspec
+          RSpec.configure do |config|
+            config.before(:each, type: :feature) do
+              ::Capybara.current_driver = ::Capybara.javascript_driver
+              IntegrationTestsRails::Capybara::Util.ensure_server_ready(self)
+            end
+
+            config.include(Helper, type: :feature, unit: true)
+          end
+        end
+
+        def verbose?
+          IntegrationTestsRails.configuration.verbose
+        end
+
+        def log(message)
+          puts "[CAPYBARA] #{message}" if verbose?
+        end
+      end
+    end
+  end
+end

data/lib/integration_tests_rails/capybara.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'capybara/cuprite'
+require_relative 'capybara/util'
+require_relative 'capybara/remote'
+require_relative 'capybara/local'
+
+module IntegrationTestsRails
+  # This contains the Capybara setup and configuration.
+  module Capybara
+    class << self
+      def setup
+        config = IntegrationTestsRails.configuration
+
+        ::Capybara.javascript_driver = :cuprite
+
+        if config.remote
+          Remote.setup
+        else
+          Local.setup
+        end
+
+        Util.configure_rspec
+        Util.configure_webmock
+      end
+    end
+  end
+end

data/lib/integration_tests_rails/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module IntegrationTestsRails
+  # Configuration class for this gem to modify adjustable settings for Capybara, Cuprite and Istanbul.
+  class Configuration
+    attr_accessor :source_dir, :output_dir, :backup_dir, :coverage_path, :wait_time, :remote, :chrome_url,
+                  :verbose, :timeout, :server_host, :server_port, :puma_threads, :window_size, :max_server_retries
+
+    def initialize
+      @backup_dir = 'tmp/js_backup'
+      @chrome_url = nil
+      @coverage_path = 'coverage/nyc'
+      @max_server_retries = 1000
+      @output_dir = 'tmp/instrumented_js'
+      @puma_threads = '1:1'
+      @remote = false
+      @server_host = '0.0.0.0' # rubocop:disable Style/IpAddresses
+      @server_port = nil
+      @source_dir = 'app/javascript'
+      @timeout = 30
+      @verbose = false
+      @wait_time = 5
+      @window_size = [1920, 1080]
+    end
+
+    def source_path
+      Rails.root.join(source_dir)
+    end
+
+    def output_path
+      Rails.root.join(output_dir)
+    end
+
+    def backup_path
+      Rails.root.join(backup_dir)
+    end
+
+    def coverage_dir
+      Rails.root.join(coverage_path)
+    end
+
+    def coverage_file
+      coverage_dir.join('coverage.json')
+    end
+  end
+end

data/lib/integration_tests_rails/istanbul/collector.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'pathname'
+require 'shellwords'
+
+module IntegrationTestsRails
+  module Istanbul
+    # Collects reports and manages instrumented files.
+    module Collector
+      class << self
+        def setup
+          config = IntegrationTestsRails.configuration
+
+          # Instrument files
+          Instrumenter.instrument_all
+
+          # Backup and replace original files
+          backup_and_replace_files
+
+          # Clean previous coverage data
+          coverage_dir = config.coverage_dir
+          FileUtils.rm_rf(coverage_dir)
+          FileUtils.mkdir_p(coverage_dir)
+        end
+
+        def collect(page)
+          coverage_data = page.evaluate_script('window.__coverage__')
+          save_coverage_snapshot(coverage_data) if coverage_data.present?
+        rescue StandardError => e
+          Util.log "Coverage collection failed: #{e.message}"
+        end
+
+        def generate_report
+          # Generate report using Node.js (will merge all snapshot files)
+          report_script = build_report_script
+          output = `node -e #{Shellwords.escape(report_script)} 2>&1`.strip
+
+          # Parse and display coverage summary
+          return if output.blank?
+
+          begin
+            data = JSON.parse(output)
+            puts "\nJavaScript Coverage: #{data['covered']} / #{data['total']} LOC (#{data['pct']}%) covered."
+            puts "Coverage report: coverage/javascript/index.html\n"
+          rescue JSON::ParserError
+            puts output
+          end
+        end
+
+        def restore_original_files
+          config = IntegrationTestsRails.configuration
+
+          backup_dir = config.backup_path
+          source_dir = config.source_path
+
+          return unless Dir.exist?(backup_dir)
+
+          FileUtils.rm_rf(source_dir)
+          FileUtils.cp_r(backup_dir, source_dir)
+          Util.log '✓ Restored original JavaScript files'
+        end
+
+        private
+
+        def backup_and_replace_files
+          config = IntegrationTestsRails.configuration
+          source_path = config.source_path
+          backup_path = config.backup_path
+          output_path = config.output_path
+
+          # Backup originals
+          FileUtils.rm_rf(backup_path)
+          FileUtils.cp_r(source_path, backup_path)
+
+          # Replace with instrumented
+          Dir.glob(output_path.join('**/*.js')).each do |instrumented_file|
+            relative_path = Pathname.new(instrumented_file).relative_path_from(output_path)
+            target_file = source_path.join(relative_path)
+            FileUtils.cp(instrumented_file, target_file)
+          end
+        end
+
+        def save_coverage_snapshot(coverage_data)
+          config = IntegrationTestsRails.configuration
+
+          snapshot_file = config.coverage_dir.join("js-#{Time.now.to_f.to_s.tr('.', '-')}.json")
+          File.write(snapshot_file, JSON.pretty_generate(coverage_data))
+        end
+
+        def build_report_script
+          config = IntegrationTestsRails.configuration
+
+          <<~JS
+            const libCoverage = require('istanbul-lib-coverage');
+            const libReport = require('istanbul-lib-report');
+            const reports = require('istanbul-reports');
+            const fs = require('fs');
+            const path = require('path');
+
+            const coverageDir = '#{config.coverage_dir}';
+            const files = fs.readdirSync(coverageDir).filter(f => f.startsWith('js-') && f.endsWith('.json'));
+
+            const coverageMap = libCoverage.createCoverageMap();
+
+            files.forEach(file => {
+              const filePath = path.join(coverageDir, file);
+              const coverage = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+              coverageMap.merge(coverage);
+            });
+
+            // Add all instrumented files (even those with 0% coverage)
+            function findJsFiles(dir, fileList = []) {
+              const items = fs.readdirSync(dir);
+              items.forEach(item => {
+                const fullPath = path.join(dir, item);
+                const stat = fs.statSync(fullPath);
+                if (stat.isDirectory()) {
+                  findJsFiles(fullPath, fileList);
+                } else if (item.endsWith('.js')) {
+                  fileList.push(fullPath);
+                }
+              });
+              return fileList;
+            }
+
+            const instrumentedDir = '#{config.output_path}';
+            const instrumentedFiles = findJsFiles(instrumentedDir);
+
+            instrumentedFiles.forEach(instrumentedFile => {
+              const relativePath = path.relative(instrumentedDir, instrumentedFile);
+              const originalFile = path.join('#{config.source_path}', relativePath);
+
+              if (coverageMap.data[originalFile]) return;
+
+              try {
+                const code = fs.readFileSync(instrumentedFile, 'utf8');
+                const match = code.match(/var coverageData = (\\{[\\s\\S]+?\\});/);
+
+                if (match && match[1]) {
+                  const coverageData = eval('(' + match[1] + ')');
+                  coverageData.path = originalFile;
+                  coverageMap.addFileCoverage(coverageData);
+                }
+              } catch(e) {
+                // Skip files that can't be parsed
+              }
+            });
+
+            const context = libReport.createContext({
+              dir: 'coverage/javascript',
+              coverageMap: coverageMap
+            });
+
+            ['html', 'lcov', 'cobertura'].forEach(reportType => {
+              const report = reports.create(reportType, {});
+              report.execute(context);
+            });
+
+            const summary = coverageMap.getCoverageSummary();
+            console.log(JSON.stringify({
+              covered: summary.lines.covered,
+              total: summary.lines.total,
+              pct: summary.lines.pct.toFixed(2)
+            }));
+          JS
+        end
+      end
+    end
+  end
+end

data/lib/integration_tests_rails/istanbul/instrumenter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'pathname'
+require 'shellwords'
+
+module IntegrationTestsRails
+  module Istanbul
+    # Instruments JavaScript files for code coverage using Istanbul.
+    module Instrumenter
+      class << self
+        def instrument_all
+          config = IntegrationTestsRails.configuration
+          output_path = config.output_path
+
+          # Clean output directory
+          FileUtils.rm_rf(output_path)
+          FileUtils.mkdir_p(output_path)
+
+          # Find all JS files
+          js_files = Dir.glob(config.source_path.join('**/*.js'))
+          Util.log "Instrumenting #{js_files.length} JavaScript files..."
+
+          js_files.each do |file|
+            instrument_file(file)
+          end
+
+          Util.log '✓ Instrumented files created'
+          Util.log '=== Istanbul Instrumentation Complete ==='
+        end
+
+        def instrument_file(file)
+          config = IntegrationTestsRails.configuration
+
+          relative_path = Pathname.new(file).relative_path_from(config.source_path)
+          output_file = config.output_path.join(relative_path)
+
+          FileUtils.mkdir_p(output_file.dirname)
+
+          # Use Node.js to instrument the file
+          code = File.read(file)
+          escaped_code = JSON.generate(code)
+          escaped_file = JSON.generate(file.to_s)
+
+          js_command = <<~JS
+            const { createInstrumenter } = require('istanbul-lib-instrument');
+            const instrumenter = createInstrumenter({ esModules: true, compact: false });
+            const code = #{escaped_code};
+            const filename = #{escaped_file};
+            console.log(instrumenter.instrumentSync(code, filename));
+          JS
+
+          instrumented = `node -e #{Shellwords.escape(js_command)}`.strip
+
+          if $CHILD_STATUS.success?
+            File.write(output_file, instrumented)
+          else
+            warn "Failed to instrument #{relative_path}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/integration_tests_rails/istanbul/util.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module IntegrationTestsRails
+  module Istanbul
+    # Utilities for Istanbul setup and configuration are found here.
+    module Util
+      class << self
+        def configure_rspec
+          RSpec.configure do |config|
+            config.before(:suite) do
+              Instrumenter.instrument_all
+              Collector.setup
+            end
+
+            config.after(:each, type: :feature) do
+              Collector.collect(page)
+            end
+          end
+        end
+
+        def log(message)
+          return unless verbose?
+
+          puts "[ISTANBUL] #{message}"
+        end
+
+        private
+
+        def verbose?
+          IntegrationTestsRails.configuration&.verbose
+        end
+      end
+    end
+  end
+end

data/lib/integration_tests_rails/istanbul.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'istanbul/instrumenter'
+require_relative 'istanbul/collector'
+require_relative 'istanbul/util'
+
+module IntegrationTestsRails
+  # This contains the Istanbul setup and configuration.
+  module Istanbul
+    class << self
+      def setup
+        Util.configure_rspec
+      end
+    end
+
+    # Ensure cleanup at exit, either success, failure or cancellation.
+    at_exit do
+      Collector.generate_report
+      Collector.restore_original_files
+    rescue StandardError => e
+      warn "Istanbul cleanup failed: #{e.message}"
+    end
+  end
+end

data/lib/integration_tests_rails/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module IntegrationTestsRails
+  VERSION = '0.1.0'
+end

data/lib/integration_tests_rails.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'integration_tests_rails/version'
+require_relative 'integration_tests_rails/configuration'
+require_relative 'integration_tests_rails/istanbul'
+require_relative 'integration_tests_rails/capybara'
+
+# The main module for the IntegrationTestsRails gem.
+module IntegrationTestsRails
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Convenience method to set up everything at once
+    def setup
+      yield(configuration) if block_given?
+
+      Capybara.setup
+      Istanbul.setup
+    end
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: integration-tests-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tien
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: cuprite
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+email:
+- tieeeeen1994@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/generators/integration_tests_rails/install_generator.rb
+- lib/generators/integration_tests_rails/templates/tests_controller.rb
+- lib/integration_tests_rails.rb
+- lib/integration_tests_rails/capybara.rb
+- lib/integration_tests_rails/capybara/helpers.rb
+- lib/integration_tests_rails/capybara/local.rb
+- lib/integration_tests_rails/capybara/remote.rb
+- lib/integration_tests_rails/capybara/util.rb
+- lib/integration_tests_rails/configuration.rb
+- lib/integration_tests_rails/istanbul.rb
+- lib/integration_tests_rails/istanbul/collector.rb
+- lib/integration_tests_rails/istanbul/instrumenter.rb
+- lib/integration_tests_rails/istanbul/util.rb
+- lib/integration_tests_rails/version.rb
+homepage: https://github.com/tieeeeen1994/integration-tests-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tieeeeen1994/integration-tests-rails
+  source_code_uri: https://github.com/tieeeeen1994/integration-tests-rails
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Integration Testing for Rails applications using Istanbul, Cuprite, Capybara
+  and RSpec specifically.
+test_files: []