integration-tests-rails 1.0.8 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd9324031c217a8ec83714af3b5e4aa13970d8f7207329dec77cf7eac9e67f77
-  data.tar.gz: 063caea1b6bb80fd619cb1fb9cde292140282b5d9943c5bd7d35cbdf11e1942f
+  metadata.gz: a76f78f94ceebb76953e47c1d45a2e4b39f3f5260e3238721861bf6102522690
+  data.tar.gz: 2e2c200ec76728898e642ece116eb1ad163490f55a6a855c7dc8a96dc7f03cb1
 SHA512:
-  metadata.gz: 63ca3042ff7f05e8f785f79c396b644267fb3570599bb4a7f21ca6034a58dc75460ee71d396af671502e0721a012b63daeabe22683fc24b7f825951ddce5606a
-  data.tar.gz: d5a1972b1930d8ae3d68b1c2498cc2a08d496d32d18af7ca1274b3e6999be06b8a6990e9b58988c364c492ecf0e997649a0e8fdd75fa94adc376c6ed61dd62ab
+  metadata.gz: cb4e8d66540dd7b3a854af21a5fad11c439fc3c8a31b8aa96f7a9dcab74e9a2f97c6d30478201b9e2afb057121f5ca89a8c36a1019a0548e93d241c4e96171c5
+  data.tar.gz: 52227cad3110ba38c617a671614419fb321a0f58a05249ed5957a5d46f2881c0ff3cf09a3e792f28e8b9881b073be97303a53329c2f73a8970e1bce5d3061347

data/README.md

@@ -13,6 +13,8 @@ This gem is designed to facilitate integration testing in Ruby on Rails applicat
 
 ## Getting Started
 
+Gem is easy to setup.
+
 ### Installation
 
 Add this line to your Rails application's Gemfile:
@@ -64,6 +66,8 @@ IntegrationTestsRails.setup do |config|
   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.retry_attempts = 1 # Number of times to retry a test if an example fails inside a retry_on_fail block.
+  config.retry_sleep_duration = 0 # Number of seconds to wait between retries inside a retry_on_fail block.
   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.
@@ -76,6 +80,14 @@ end
 
 ## Unit Testing JavaScript Code
 
+This feature is **EXPERIMENTAL** and may change in future releases. It allows you to write unit tests for JavaScript code using RSpec and Capybara. To enable the feature, one must set the `experimental_features` configuration option to `true`:
+
+```ruby
+IntegrationTestsRails.setup do |config|
+  config.experimental_features = true
+end
+```
+
 ### Usage
 
 To unit test JavaScript code, the gem will visit a test HTML page. By default, it only renders a complete HTML page that also loads importmap-supporting JavaScript code to set up the environment for testing.
@@ -211,12 +223,42 @@ In such cases where `script` is an array, the `result` component will contain th
 
 Refer to [Cuprite](https://github.com/rubycdp/cuprite) and [Capybara](https://github.com/teamcapybara/capybara). Use them as normally in integration tests.
 
+## Retrying Flaky Tests
+
+In practice, this is frowned upon. However, in such cases where there exists a flaky test (e.g. network issues, timing issues, third-party services respnsiveness, etc.), the gem provides a way to retry tests through `retry_on_fail`.
+
+```ruby
+RSpec.describe 'Flaky Test', type: :feature do
+  describe 'Flaky Behavior' do
+    it 'must succeed' do
+      visit '/form_with_complex_javascript'
+      retry_on_fail do
+        check 'Checkbox that executes scripts with animations'
+        expect(page).to have_css('div#animated-element', visible: :visible, wait: 5)
+      end
+
+      expect(page).to have_content('Complex Modal Opened')
+    end
+  end
+end
+```
+
+The above will retry the test if the browser was not able to find the checkbox or the page was not able to find the animated element. The number of retries and sleep duration between retries can be configured through `retry_attempts` and `retry_sleep_duration` configuration options respectively. The default number of retries is 1 and the default sleep duration is 0 seconds. You can also pass them as arguments:
+
+```ruby
+retry_on_fail(retry_attempts: 3, retry_sleep_duration: 1) do
+  expect(page).to have_css('div#animated-element', visible: :visible, wait: 5)
+end
+```
+
 ## JavaScript Coverage Reports
 
 After the tests (successful, failed or cancelled), coverage reports will be generated in `coverage/javascript` by default.
 
 ## Example Setups
 
+The following are working examples.
+
 ### Using Docker Desktop
 
 If you want to use the [Alpine Chrome](https://hub.docker.com/r/zenika/alpine-chrome) image, this is definitely possible.
@@ -256,6 +298,11 @@ IntegrationTestsRails.setup do |config|
 end
 ```
 
+## TODO
+
+1. JavaScript unit testing needs to have a way to define the JavaScript loader in the spec file itself instead of in `IntegrationTestsRails.configuration.tests_page_html`.
+2. There is no graceful way to stop failing CDNs from being retried. Find a way to wait for them to complete loading. It should respect the `IntegrationTestsRails.configuration.timeout` setting.
+
 ## Contributing
 
 1. Fork the repository.

data/lib/integration_tests_rails/capybara/dsl.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module IntegrationTestsRails
+  module Capybara
+    # This module provides the main DSL for writing integration tests with Capybara.
+    module Dsl
+      def retry_on_fail(attempts: nil, sleep_duration: nil)
+        config = IntegrationTestsRails.configuration
+        attempts ||= config.retry_attempts
+        sleep_duration ||= config.retry_sleep_duration
+        counter = 0
+
+        begin
+          yield
+        rescue RSpec::Expectations::ExpectationNotMetError, Capybara::ElementNotFound => e
+          counter += 1
+          Util.log("Attempt #{counter} for #{RSpec.current_example.full_description} failed!")
+          raise e if counter >= attempts
+
+          sleep(sleep_duration) if sleep_duration.positive?
+          retry
+        end
+      end
+    end
+  end
+end

data/lib/integration_tests_rails/capybara/helpers.rb

@@ -37,6 +37,7 @@ module IntegrationTestsRails
       let(:function) { nil }
 
       before do
+        # page.driver.wait_for_network_idle(timeout: IntegrationTestsRails.configuration.timeout)
         visit '/tests'
         result
       end

data/lib/integration_tests_rails/capybara/remote.rb

@@ -34,6 +34,10 @@ module IntegrationTestsRails
             timeout = config.timeout
             options = {
               window_size: config.window_size,
+              browser_options: {
+                'no-sandbox': nil,
+                'disable-dev-shm-usage': nil
+              },
               url: config.chrome_url,
               timeout: timeout,
               process_timeout: timeout

data/lib/integration_tests_rails/capybara/util.rb

@@ -16,12 +16,15 @@ module IntegrationTestsRails
         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
+          configuration = IntegrationTestsRails.configuration
+          server_retries = configuration.max_server_retries
           server_retries.times do |attempt|
-            context.visit('/400')
+            if configuration.experimental_features
+              context.visit('/tests')
+            else
+              context.visit('/')
+            end
             @server_ready = true
             log 'Server is ready!'
             break
@@ -33,16 +36,21 @@ module IntegrationTestsRails
 
         def configure_rspec
           RSpec.configure do |config|
+            config.include Dsl, type: :feature
             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)
+            if IntegrationTestsRails.configuration.experimental_features
+              config.include(Helper, type: :feature, unit: true)
+            end
           end
         end
 
         def configure_routes
+          return unless IntegrationTestsRails.configuration.experimental_features
+
           app = Rails.application
           routes = app.routes
           # Use append and let Rails handle finalization automatically

data/lib/integration_tests_rails/configuration.rb

@@ -39,16 +39,20 @@ module IntegrationTestsRails
 
     attr_accessor :source_dir, :output_dir, :backup_dir, :coverage_path, :wait_time, :remote,
                   :chrome_url, :tests_page_html, :window_size, :max_server_retries,
-                  :verbose, :timeout, :server_host, :server_port, :puma_threads
+                  :verbose, :timeout, :server_host, :server_port, :puma_threads, :experimental_features,
+                  :retry_attempts, :retry_sleep_duration
 
     def initialize
       @backup_dir = 'tmp/js_backup'
       @chrome_url = nil
       @coverage_path = 'coverage/nyc'
+      @experimental_features = false
       @max_server_retries = 1000
       @output_dir = 'tmp/instrumented_js'
       @puma_threads = '1:1'
       @remote = false
+      @retry_attempts = 1
+      @retry_sleep_duration = 0
       @server_host = '0.0.0.0' # rubocop:disable Style/IpAddresses
       @server_port = nil
       @source_dir = 'app/javascript'

data/lib/integration_tests_rails/istanbul/instrumenter.rb

@@ -32,27 +32,45 @@ module IntegrationTestsRails
 
         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)
+          instrumented = instrument_code_with_istanbul(code, file)
+
+          write_instrumented_file(output_file, instrumented, relative_path)
+        end
+
+        private
+
+        def instrument_code_with_istanbul(code, file)
+          require 'tempfile'
+          Tempfile.create(['code', '.js']) do |temp_code|
+            temp_code.write(code)
+            temp_code.flush
+
+            js_command = build_istanbul_command(temp_code.path, file)
+            `node -e #{Shellwords.escape(js_command)}`.strip
+          end
+        end
+
+        def build_istanbul_command(code_path, file)
+          escaped_code_path = JSON.generate(code_path)
           escaped_file = JSON.generate(file.to_s)
 
-          js_command = <<~JS
+          <<~JS
+            const fs = require('fs');
             const { createInstrumenter } = require('istanbul-lib-instrument');
             const instrumenter = createInstrumenter({ esModules: true, compact: false });
-            const code = #{escaped_code};
+            const code = fs.readFileSync(#{escaped_code_path}, 'utf8');
             const filename = #{escaped_file};
             console.log(instrumenter.instrumentSync(code, filename));
           JS
+        end
 
-          instrumented = `node -e #{Shellwords.escape(js_command)}`.strip
-
+        def write_instrumented_file(output_file, instrumented, relative_path)
           if $CHILD_STATUS.success?
             File.write(output_file, instrumented)
           else

data/lib/integration_tests_rails/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: integration-tests-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 1.1.0
 platform: ruby
 authors:
 - Tien
@@ -90,6 +90,7 @@ files:
 - lib/integration-tests-rails.rb
 - lib/integration_tests_rails.rb
 - lib/integration_tests_rails/capybara.rb
+- lib/integration_tests_rails/capybara/dsl.rb
 - lib/integration_tests_rails/capybara/helpers.rb
 - lib/integration_tests_rails/capybara/local.rb
 - lib/integration_tests_rails/capybara/remote.rb