Enable verbose output from CI debug environment variables.

Automatically enable verbose output when a CI provider is running in
debug mode, e.g. GitHub Actions re-run with "Enable debug logging"
(RUNNER_DEBUG=1). Also supports GitLab CI, Buildkite, Azure Pipelines,
and an explicit SUS_VERBOSE toggle.

Assisted-By: devx/0e90505d-10c5-4dfa-be04-c43abc87164a

Author: samuel-williams-shopify

lib/sus/config.rb

@@ -38,12 +38,40 @@ def self.load(root: Dir.pwd, arguments: ARGV)
 			end
 
 			options = {
-				verbose: !!arguments.delete("--verbose")
+				verbose: !!arguments.delete("--verbose") || self.verbose_from_environment?
 			}
 
 			return derived.new(root, arguments, **options)
 		end
 
+		# Maps CI environment variables to the values they take when the CI provider is running in debug/verbose mode. When any of these match, we enable verbose output automatically.
+		#
+		# - `RUNNER_DEBUG` is set by GitHub Actions when a workflow is re-run with "Enable debug logging".
+		# - `CI_DEBUG_TRACE` is set by GitLab CI when debug logging (tracing) is enabled.
+		# - `BUILDKITE_AGENT_DEBUG` is set by Buildkite when agent debug is enabled.
+		# - `SYSTEM_DEBUG` is set by Azure Pipelines when the `system.debug` variable is enabled.
+		# - `SUS_VERBOSE` can be set explicitly to enable verbose output regardless of the CI provider.
+		DEBUG_ENVIRONMENT = {
+			"SUS_VERBOSE" => "true",
+			"RUNNER_DEBUG" => "1",
+			"CI_DEBUG_TRACE" => "true",
+			"BUILDKITE_AGENT_DEBUG" => "true",
+			"SYSTEM_DEBUG" => "true",
+		}
+		
+		# Whether verbose output should be enabled based on the environment.
+		#
+		# Detects CI environments that request debug logging, e.g. GitHub Actions
+		# sets `RUNNER_DEBUG=1` when a workflow is re-run with "Enable debug logging".
+		#
+		# @parameter env [Hash] The environment to inspect.
+		# @returns [Boolean] Whether verbose output should be enabled.
+		def self.verbose_from_environment?(env = ENV)
+			DEBUG_ENVIRONMENT.any? do |key, value|
+				env[key] == value
+			end
+		end
+		
 		# Initialize a new Config instance.
 		# @parameter root [String] The root directory for the project.
 		# @parameter paths [Array] Optional paths to specific test files.

test/sus/config.rb

@@ -22,6 +22,48 @@ def print(output)
 		expect(config).not.to be(:nil?)
 	end
 
+	with ".verbose_from_environment?" do
+		it "is enabled by GitHub Actions debug logging" do
+			expect(subject.verbose_from_environment?({"RUNNER_DEBUG" => "1"})).to be == true
+		end
+		
+		it "is enabled by GitLab CI debug tracing" do
+			expect(subject.verbose_from_environment?({"CI_DEBUG_TRACE" => "true"})).to be == true
+		end
+		
+		it "is enabled by Buildkite agent debug" do
+			expect(subject.verbose_from_environment?({"BUILDKITE_AGENT_DEBUG" => "true"})).to be == true
+		end
+		
+		it "is enabled by Azure Pipelines system debug" do
+			expect(subject.verbose_from_environment?({"SYSTEM_DEBUG" => "true"})).to be == true
+		end
+		
+		it "is enabled by the SUS_VERBOSE environment variable" do
+			expect(subject.verbose_from_environment?({"SUS_VERBOSE" => "true"})).to be == true
+		end
+		
+		it "is disabled by default" do
+			expect(subject.verbose_from_environment?({})).to be == false
+		end
+		
+		it "ignores unrelated values" do
+			expect(subject.verbose_from_environment?({"RUNNER_DEBUG" => "0"})).to be == false
+		end
+	end
+	
+	with "#verbose?" do
+		it "is enabled by the --verbose argument" do
+			config = subject.load(root: root, arguments: ["--verbose"])
+			expect(config).to be(:verbose?)
+		end
+		
+		it "is disabled by default" do
+			config = subject.load(root: root, arguments: [])
+			expect(config).not.to be(:verbose?)
+		end
+	end
+	
 	with "summary output" do
 		let(:io) {StringIO.new}
 		let(:output) {Sus::Output::Text.new(io)}