minitest-fork_executor 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e731cf4446b5cd86c62960733c6b246ddb448b0ec3de336dfffce8a4dd3ec42a
-  data.tar.gz: f576f6b03abe886997f9e8aa7769f78fd6d8e0ac83aeeabff7e01a9e6ff9e1f0
+  metadata.gz: 6bd1e593335a149a422ff23630519000bd5f84e04bb8855682bd98511b07c6d1
+  data.tar.gz: 35f0d39d2498bd157e547ba852680a82fe3b5566616a7cdd28fa81b947cb160b
 SHA512:
-  metadata.gz: 8ff4e0922b3282c87b4c39de27aac33173e56d9cc0d4362591050a33cc4e6483a6b0071a23862f93a60c8e530a95d4830dd6a486fa7b87dc31df65cbca204b3b
-  data.tar.gz: 63eafec89873a5828f170f321bffaef38bb1a64e051345536c7073c6b725b978aecdf1de4016ce6fef78822e3f4c759f89c00e539c543b4d7e957c268107c4cf
+  metadata.gz: fc6a7ebe2f72cd6214469d3755325839289b0c65e05fa32544981bd2badbf865822ca62c07eeb731e39ce3f9267971b1426d092d37a68e6ec993083e4757b7b6
+  data.tar.gz: de20c9433516f9bfd89275e9d08802aa0ae50c2ffe5de60676dc148898012f000532328a67126a77600243452f297ea74c656bdbf5a9cba7ccb22568ceca1fcb

data/lib/minitest/fork_executor.rb

@@ -1,49 +1,112 @@
 module Minitest
+  # Minitest runs individual test cases via Minitest.run_one_method. When
+  # ForkExecutor is started, we need to override it and implement the fork
+  # algorithm. See the detailed comments below to understand how it's done.
+  #
+  # Please keep in mind we support Ruby 1.9 and hence can't use conveniences
+  # offered by more modern Rubies.
+
   class ForkExecutor
-    # Minitest runs individual test cases via Minitest.run_one_method. When
-    # ForkExecutor is started, we need to override it and implement the fork
-    # algorithm. See the detailed comments below to understand how it's done.
-    #
-    # Please keep in mind we support Ruby 1.9 and hence can't use conveniences
-    # offered by more modern Rubies.
-    def start
-      # Store the reference to the original run_one_method singleton method.
-      original_run_one_method = Minitest.method(:run_one_method)
+    # Run a fork-based test case. The block passed to the method should actually
+    # run the test using the original code from Minitest.
+    def self.run
+      # Set up a binary pipe for transporting test results from the child
+      # to the parent process.
+      read_io, write_io = IO.pipe
+      read_io.binmode
+      write_io.binmode
+
+      if Process.fork
+        # The parent process responsible for collecting results.
+
+        # The parent process doesn't write anything.
+        write_io.close
+
+        # Load the result object passed by the child process.
+        result = Marshal.load(read_io)
+
+        # Unwrap all failures from FailureTransport so that they can be
+        # safely presented to the user.
+        result.failures.map!(&:failure)
+
+        # We're done reading results from the child so it's safe to close the
+        # IO object now.
+        read_io.close
+
+        # Wait for the child process to finish before returning the result.
+        Process.wait
+      else
+        # The child process responsible for running the test case.
+
+        # Run the test case method via the original .run_one_method.
+        result = yield
+
+        # Wrap failures in FailureTransport to avoid issue when marshalling.
+        # Some failures correspond to exceptions referencing unmarshallable
+        # objects. For example, a PostgreSQL exception may reference
+        # PG::Connection that cannot be marshalled. In those case, we replace
+        # the original error with UnmarshallableError retaining as much
+        # detail as possible.
+        result.failures.map! { |failure| FailureTransport.new(failure) }
 
-      # Remove the original singleton method from Minitest in order to avoid
-      # method redefinition warnings when patching it in the next step.
-      class << Minitest
-        remove_method(:run_one_method)
+        # The child process doesn't read anything.
+        read_io.close
+
+        # Dump the result object to the write IO object so that it can be
+        # read by the parent process.
+        Marshal.dump(result, write_io)
+
+        # We're done sending results to the parent so it's safe to close the
+        # IO object now.
+        write_io.close
+
+        # Exit the child process as its job is now done.
+        exit
       end
 
-      # Define a new version of run_one_method that forks, calls the original
-      # run_one_method in the child process, and sends results back to the
-      # parent.
-      Minitest.define_singleton_method(:run_one_method) do |klass, method_name|
-        read_io, write_io = IO.pipe
-        read_io.binmode
-        write_io.binmode
+      # This value is returned ONLY in the parent process, not in the child
+      # process.
+      result
+    end
+
+    # #start is called by Minitest when initializing the executor. This is where
+    # we override some Minitest internals to implement fork-based execution.
+    def start
+      if Minitest.respond_to?(:run_one_method)
+        # Minitest 5
 
-        if fork
-          # Parent: load the result sent from the child
+        # Store the reference to the original run_one_method method in order to
+        # use it to actually run the test case.
+        original_run_one_method = Minitest.method(:run_one_method)
 
-          write_io.close
-          result = Marshal.load(read_io)
-          read_io.close
+        # Remove the original singleton method from Minitest in order to avoid
+        # method redefinition warnings when patching it in the next step.
+        class << Minitest
+          remove_method(:run_one_method)
+        end
 
-          Process.wait
-        else
-          # Child: just run normally, dump the result, and exit the process to
-          # avoid double-reporting.
-          result = original_run_one_method.call(klass, method_name)
-
-          read_io.close
-          Marshal.dump(result, write_io)
-          write_io.close
-          exit
+        # Define a new version of run_one_method that forks, calls the original
+        # run_one_method in the child process, and sends results back to the
+        # parent. klass and method_name are the two parameters accepted by the
+        # original run_one_method - they're the test class (e.g. UserTest) and
+        # the test method name (e.g. :test_email_must_be_unique).
+        Minitest.define_singleton_method(:run_one_method) do |klass, method_name|
+          ForkExecutor.run do
+            original_run_one_method.call(klass, method_name)
+          end
         end
+      else
+        # Minitest 6
 
-        result
+        Runnable.runnables.each do |runnable_class|
+          original_run_method = runnable_class.instance_method(:run)
+          runnable_class.define_method(:run) do
+            bound_original_run_method = original_run_method.bind(self)
+            ForkExecutor.run do
+              bound_original_run_method.call
+            end
+          end
+        end
       end
     end
 
@@ -51,5 +114,73 @@ module Minitest
       # Nothing to do here but required by Minitest. In a future version, we may
       # reinstate the original Minitest.run_one_method here.
     end
+
+    # A Minitest Failure transport class enabling passing non-marshallable
+    # objects (e.g. IO or sockets) via Marshal. The basic idea is replacing
+    # Minitest failures referencing unmarshallable objects with
+    # UnmarshallableError retaining as much detail as possible.
+    class FailureTransport
+      attr_reader :failure
+
+      def initialize(failure)
+        @failure = failure
+      end
+
+      def marshal_dump
+        Marshal.dump(failure)
+      rescue TypeError
+        # CAREFUL! WE'RE MODIFYING FAILURE IN PLACE UNDER THE ASSUMPTION THAT
+        # IT LIVES IN A MEMORY SPACE OF A SHORT-LIVED PROCESS, NAMELY THE CHILD
+        # PROCESS RESPONSIBLE FOR RUNNING A SINGLE TEST. IF THIS ASSUMPTION IS
+        # VIOLATED THEN AN ALTERNATIVE APPROACH (E.G. DUPLICATING THE FAILURE)
+        # MIGHT BE NECESSARY.
+
+        if failure.respond_to?(:exception) && failure.respond_to?(:exception=)
+          failure.exception = UnmarshallableError.new(failure.exception)
+        elsif failure.respond_to?(:error) && failure.respond_to?(:error=)
+          failure.error = UnmarshallableError.new(failure.error)
+        else
+          raise(<<ERROR)
+Minitest failures should respond respond to exception/exception= (versions prior
+to 5.14.0) or error/error= (version 5.14.0 and newer). The received failure does
+responds to neither. Are you using an newer Minitest version?
+ERROR
+        end
+
+        Marshal.dump(failure)
+      end
+
+      def marshal_load(dump)
+        @failure = Marshal.load(dump)
+      end
+    end
+
+    # An always marshallable exception class that can be derived from another
+    # (potentially non-marshallable exception). It's actually not intended to be
+    # raised but merely instantiated when passing Minitest failures from the
+    # runner to the reporter.
+    class UnmarshallableError < RuntimeError
+      def initialize(exc)
+        super(<<MESSAGE)
+An unmarshallable error has occured. Below is its best-effort representation.
+In order to receive the error itself, please disable Minitest::ForkExecutor.
+
+Error class:
+#{exc.class.name}
+
+Error message:
+#{exc.message}
+
+Attributes:
+#{exc.instance_variables.map do |name|
+  "  #{name} = #{exc.instance_variable_get(name).inspect}"
+end.join("\n")}
+
+END OF ERROR MESSAGE (ORIGINAL BACKTRACE MAY FOLLOW)
+MESSAGE
+
+        set_backtrace(exc.backtrace)
+      end
+    end
   end
 end

data/test/acceptance/unmarshallable_test.rb

@@ -0,0 +1,34 @@
+require 'tempfile'
+
+require 'minitest/autorun'
+require 'minitest/fork_executor'
+
+Minitest.parallel_executor = Minitest::ForkExecutor.new
+
+class UnmarshallableException < RuntimeError
+  def initialize(io)
+    super("Unmarshallable test exception")
+    @io = io
+  end
+end
+
+class UnmarshallableTest < Minitest::Test
+  def test_unmarshallable_wrapping
+    # We'd like to see a backtrace in the output hence several raise_in_* calls.
+    raise_in_2
+  end
+
+  private
+
+  def raise_in_2
+    raise_in_1
+  end
+
+  def raise_in_1
+    raise_in_0
+  end
+
+  def raise_in_0
+    raise UnmarshallableException.new($stdout)
+  end
+end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: minitest-fork_executor
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Greg Navis
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
 date: 2019-01-03 00:00:00.000000000 Z
@@ -28,16 +28,30 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 12.2.1
+        version: 13.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 12.2.1
+        version: 13.0.0
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  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'
 description: Run each test_* method in a separate process thus eliminating test case
   interference.
 email: contact@gregnavis.com
@@ -46,12 +60,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/minitest/fork_executor.rb
-- test/minitest/fork_executor_test.rb
+- test/acceptance/unmarshallable_test.rb
+- test/unit/minitest/fork_executor_test.rb
 homepage: https://github.com/gregnavis/minitest-fork_executor
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -66,9 +81,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: Near-perfect process-level test case isolation.
 test_files:
-- test/minitest/fork_executor_test.rb
+- test/acceptance/unmarshallable_test.rb
+- test/unit/minitest/fork_executor_test.rb