Add --failure-exit-code option (#949)

* feat: Add failure-exit-code option

* docs: Add failure-exit-code option

* test: Add --failure-exit-code test

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Breaking Changes
 
 ### Added
+- Added `--failure-exit-code [INT]` flag to specify a custom exit code when tests fail. This option allows users to define a specific exit code that the test suite should return if any tests fail.
 
 ### Fixed
 

Readme.md

@@ -252,6 +252,8 @@ Options are:
     -i, --isolate                    Do not run any other tests in the group used by --single(-s)
         --isolate-n [PROCESSES]      Use 'isolate'  singles with number of processes, default: 1.
         --highest-exit-status        Exit with the highest exit status provided by test run(s)
+                                     If failure-exit-code is specified, that value takes priority.
+        --failure-exit-code [INT]    Specify the exit code to use when tests fail.
         --specify-groups [SPECS]     Use 'specify-groups' if you want to specify multiple specs running in multiple
                                      processes in a specific formation. Commas indicate specs in the same process,
                                      pipes indicate specs in a new process. Cannot use with --single, --isolate, or

lib/parallel_tests/cli.rb

@@ -96,8 +96,9 @@ def run_tests_in_parallel(num_processes, options)
       if any_test_failed?(test_results)
         warn final_fail_message
 
-        # return the highest exit status to allow sub-processes to send things other than 1
-        exit_status = if options[:highest_exit_status]
+        exit_status = if options[:failure_exit_code]
+          options[:failure_exit_code]
+        elsif options[:highest_exit_status]
           test_results.map { |data| data.fetch(:exit_status) }.max
         else
           1
@@ -226,9 +227,19 @@ def parse_options!(argv)
           "Use 'isolate'  singles with number of processes, default: 1."
         ) { |n| options[:isolate_count] = n }
 
-        opts.on("--highest-exit-status", "Exit with the highest exit status provided by test run(s)") do
-          options[:highest_exit_status] = true
-        end
+        opts.on(
+          "--highest-exit-status",
+          <<~TEXT.rstrip.split("\n").join("\n#{newline_padding}")
+            Exit with the highest exit status provided by test run(s)
+            If failure-exit-code is specified, that value takes priority.
+          TEXT
+        ) { options[:highest_exit_status] = true }
+
+        opts.on(
+          "--failure-exit-code [INT]",
+          Integer,
+          "Specify the exit code to use when tests fail"
+        ) { |code| options[:failure_exit_code] = code }
 
         opts.on(
           "--specify-groups [SPECS]",

spec/parallel_tests/cli_spec.rb

@@ -61,6 +61,10 @@ def call(*args)
       )
     end
 
+    it "parses --failure-exit-code" do
+      expect(call(["test", "--failure-exit-code", "42"])).to eq(defaults.merge(failure_exit_code: 42))
+    end
+
     it "parses --quiet" do
       expect(call(["test", "--quiet"])).to eq(defaults.merge(quiet: true))
     end