minitest-fork_executor 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e731cf4446b5cd86c62960733c6b246ddb448b0ec3de336dfffce8a4dd3ec42a
-  data.tar.gz: f576f6b03abe886997f9e8aa7769f78fd6d8e0ac83aeeabff7e01a9e6ff9e1f0
+  metadata.gz: e166bd6d5d09dc03b3888c59beb8a30ba259c7cef826f0bcfa373375b232151c
+  data.tar.gz: caadad6c3971b6acafbe50fc0e1a3f76f7062d8c03bfe27ba11a578ecd91920e
 SHA512:
-  metadata.gz: 8ff4e0922b3282c87b4c39de27aac33173e56d9cc0d4362591050a33cc4e6483a6b0071a23862f93a60c8e530a95d4830dd6a486fa7b87dc31df65cbca204b3b
-  data.tar.gz: 63eafec89873a5828f170f321bffaef38bb1a64e051345536c7073c6b725b978aecdf1de4016ce6fef78822e3f4c759f89c00e539c543b4d7e957c268107c4cf
+  metadata.gz: 5775181f930796a6b81c36cf265a0fe562f216e21fa6ae16c42b0dc1318c5ceacd078d580071d8d8a6f8c511d8f78b5fe7af52258930bea6787bb015a172bffc
+  data.tar.gz: 9a683822a4dd87af11d56088854e2cc10caf537388644f5f0ddabe8612b5ea92196b0b6f277a64758914fd0bc6712e33c3f90511d42d29bf707b40bc55c8dc69

data/lib/minitest/fork_executor.rb

@@ -1,13 +1,17 @@
 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.
+    # #start is called by Minitest when initializing the executor. This is where
+    # we override some Minitest internals to implement fork-based execution.
     def start
-      # Store the reference to the original run_one_method singleton method.
+      # 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)
 
       # Remove the original singleton method from Minitest in order to avoid
@@ -18,31 +22,66 @@ module Minitest
 
       # 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.
+      # 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|
+        # 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 fork
-          # Parent: load the result sent from the child
+        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
-          # Child: just run normally, dump the result, and exit the process to
-          # avoid double-reporting.
+          # The child process responsible for running the test case.
+
+          # Run the test case method via the original .run_one_method.
           result = original_run_one_method.call(klass, method_name)
 
+          # 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) }
+
+          # 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
 
+        # This value is returned ONLY in the parent process, not in the child
+        # process.
         result
       end
     end
@@ -51,5 +90,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.0.3
 platform: ruby
 authors:
 - Greg Navis
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
 date: 2019-01-03 00:00:00.000000000 Z
@@ -46,12 +46,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 +67,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.2.22
+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