ace-support-test-helpers 0.13.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6dc0530e9109d683e0b5e41530b9ff50c45aa646ecf9b289f45ad95dbe8b908
+  data.tar.gz: dea7a118cb5b6b8f8c06792a54c6400dd362836222dcccf00ea29ca537d5489c
+SHA512:
+  metadata.gz: 896cecde3a9fa17f925742f5005009004e374597ea1fc4e0d26889627420987e4a98612e9095456c5c9bcee6c439eabc2726b2d01aec3ab078ff02c360fda6ec
+  data.tar.gz: 81227f0ce16964e340c9fb8fa07d0dc7e7294dd5da226b598d2f84fa0632aebca6b88d21ce042bd4ddc6e393953bcd3739f122539ca2e4f7e8aab6d389a612d8

data/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to ace-test-support will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.13.0] - 2026-03-23
+
+### Fixed
+- Corrected `source_code_uri` gemspec metadata to point to package-specific path instead of repository root.
+
+### Technical
+- Removed phantom `handbook/**/*` glob from gemspec (no handbook directory exists).
+
+## [0.12.6] - 2026-03-22
+
+### Changed
+- Refreshed README structure for support-library consistency while preserving existing usage and utility documentation.
+- Added the canonical `Part of ACE` footer and explicit `License` section to the package README.
+
+## [0.12.5] - 2026-03-18
+
+### Changed
+- Migrated CLI namespace from `Ace::Core::CLI::*` to `Ace::Support::Cli::*` (ace-support-cli is now the canonical home for CLI infrastructure).
+
+
+## [0.12.4] - 2026-03-09
+
+### Fixed
+- `with_temp_dir` now resets cached `Ace::Bundle` configuration alongside project-root cache state so temp-dir tests remain order-independent under full non-E2E suite execution.
+
+## [0.12.3] - 2026-03-04
+
+### Fixed
+- `with_cascade_configs` now isolates HOME into a temporary directory when creating home-level config fixtures, preventing permission errors in sandboxed environments.
+
+## [0.12.2] - 2026-01-31
+
+### Fixed
+- Add `respond_to?(:get)` check to `test_stub_ace_core_config_integration` skip condition
+
+## [0.12.1] - 2026-01-31
+
+### Fixed
+- Improve `stub_ace_core_config` isolation with `respond_to?` guard and `define_singleton_method`
+
+## [0.11.1] - 2026-01-15
+
+### Changed
+- **Context Mocks Migration**: Updated ContextMocks to use Ace::Bundle
+  - Renamed all `Ace::Context` references to `Ace::Bundle`
+  - Updated mock methods: `stub_load_file`, `stub_load_auto`, `restore_load_file`, `restore_load_auto`
+  - Comments now reference ace-bundle instead of ace-context
+- Updated TestRunnerMocks default package from ace-context to ace-bundle
+
+### Technical
+- Updated contract tests to check for Ace::Bundle availability
+
+## [0.11.0] - 2026-01-07
+
+### Added
+- **CLI test helpers** for dry-cli based CLIs (task 179)
+  - `CliHelpers` module with reusable patterns for testing CLI commands
+  - `invoke_cli` - Invoke CLI and capture stdout/stderr/result
+  - `invoke_cli_stdout` - Convenience method for stdout only
+  - `assert_cli_success` - Assert CLI returns exit code 0
+  - `assert_cli_output_matches` - Assert CLI output matches pattern
+
+## [0.10.0] - 2026-01-03
+
+### Changed
+- **BREAKING**: Minimum Ruby version raised to 3.3.0 (was 3.2.0)
+- Standardized gemspec file patterns with deterministic Dir.glob
+- Added MIT LICENSE file
+
+## [0.9.3] - 2025-12-27
+
+### Changed
+
+- **Contract Test Enhancement**: Added guarded require for ace-git in git contract tests
+  - Enables integration test to exercise CommandExecutor stub with ace-git when available
+  - Part of ace-git-diff to ace-git migration
+
+## [0.9.2] - 2025-10-08
+
+### Changed
+
+- **Test Structure Migration**: Migrated to flat ATOM structure
+  - From: `test/unit/atoms/` and `test/unit/molecules/`
+  - To: `test/atoms/` and `test/molecules/`
+  - Aligns with standardized test organization across all ACE packages
+  - Simplifies test discovery and maintenance
+
+## [0.9.1] - 2025-10-08
+
+### Changed
+- **Test directory structure**: Reorganized tests to follow ATOM architecture
+  - Moved tests from flat `test/*.rb` structure to `test/unit/atoms/` and `test/unit/molecules/`
+  - Makes tests discoverable by ace-test-runner
+  - Aligns with project-wide ATOM architecture pattern (ADR-011)
+  - Files organized as:
+    - `test/unit/atoms/`: base_test_case_test.rb, test_helper_test.rb
+    - `test/unit/molecules/`: config_helpers_test.rb, test_environment_test.rb
+
+## [0.9.0] - 2025-10-05
+
+Initial release with shared test utilities for ACE ecosystem.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,29 @@
+<div align="center">
+  <h1> ACE - Support Test Helpers </h1>
+
+  Shared test harness and environment helpers for ACE packages.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-support-test-helpers"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-support-test-helpers.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+`ace-support-test-helpers` provides reusable helpers for temporary environment setup, assertions, and integration-friendly test scaffolding so that ACE packages share consistent test patterns without duplicating boilerplate.
+
+## Use Cases
+
+**Write consistent package tests** - share base test case abstractions, setup patterns, and assertions across `ace-support-*` and other ACE packages via common helper modules.
+
+**Build integration test flows** - isolate environment variables, filesystem state, and config fixtures with reliable temporary-directory and override helpers used alongside [ace-test-runner](../ace-test-runner).
+
+**Improve CI stability** - reduce flaky test behavior with shared deterministic helpers for directory management, configuration, and environment cleanup.
+
+---
+
+Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+desc "Run tests using ace-test"
+task :test do
+  sh "ace-test"
+end
+
+desc "Run tests directly (CI mode)"
+Minitest::TestTask.create(:ci)
+
+task default: :test

data/lib/ace/test_support/base_test_case.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "minitest/test"
+
+module Ace
+  module TestSupport
+    # Base test case class with common utilities for all ace-* gems
+    class BaseTestCase < Minitest::Test
+      include TestHelper
+      include SubprocessRunner
+
+      def fixture_path(path)
+        File.expand_path("fixtures/#{path}", File.dirname(caller_locations(1, 1)[0].path))
+      end
+
+      def setup
+        @original_pwd = Dir.pwd
+        super
+        # Enable test mode by default - tests needing real config use with_real_config
+        if defined?(Ace::Support::Config) && Ace::Support::Config.respond_to?(:test_mode=)
+          Ace::Support::Config.test_mode = true
+        end
+      end
+
+      def teardown
+        Dir.chdir(@original_pwd) if @original_pwd
+        super
+      end
+    end
+
+    # Alias for backward compatibility
+    AceTestCase = BaseTestCase
+  end
+end
+
+# Make AceTestCase available at top level for convenience
+AceTestCase = Ace::TestSupport::AceTestCase

data/lib/ace/test_support/cli_helpers.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Ace
+  module TestSupport
+    # CLI test helpers for ace-support-cli based CLIs
+    #
+    # This module provides reusable patterns for testing CLI commands
+    # during the Thor to ace-support-cli migration (Task 179).
+    #
+    # @example Usage in test file
+    #   require 'ace/test_support'
+    #
+    #   class CliRoutingTest < Minitest::Test
+    #     include Ace::TestSupport::CliHelpers
+    #
+    #     def test_routes_to_version
+    #       result = invoke_cli(MyGem::CLI, ["--version"])
+    #       assert_match(/\d+\.\d+\.\d+/, result[:stdout])
+    #     end
+    #   end
+    module CliHelpers
+      # Invoke a ace-support-cli CLI and capture output
+      #
+      # This helper provides a consistent pattern for testing CLI routing
+      # and command execution. It wraps CLI.start with capture_io to
+      # capture stdout/stderr.
+      #
+      # @param cli_class [Class] The CLI module/class with a .start method
+      # @param args [Array<String>] Command line arguments
+      # @return [Hash] Result hash with :stdout, :stderr, :result keys
+      #
+      # @example Basic usage
+      #   result = invoke_cli(Ace::Search::CLI, ["version"])
+      #   assert_match(/\d+\.\d+/, result[:stdout])
+      #
+      # @example Testing with options
+      #   result = invoke_cli(Ace::Search::CLI, ["search", "TODO", "--max-results", "10"])
+      #   assert_equal 0, result[:result]
+      #
+      # @note ace-support-cli calls exit(0) for --help, so we catch SystemExit.
+      #   Commands raise Ace::Support::Cli::Error for controlled failures
+      #   (exception-based exit code pattern per ADR-023).
+      def invoke_cli(cli_class, args)
+        stdout, stderr = capture_io do
+          @_cli_result = cli_class.start(args)
+        rescue SystemExit => e
+          @_cli_result = e.status
+        rescue Ace::Support::Cli::Error => e
+          warn e.message
+          @_cli_result = e.exit_code
+        end
+
+        {
+          stdout: stdout,
+          stderr: stderr,
+          result: @_cli_result
+        }
+      end
+
+      # Invoke CLI and return only stdout (convenience method)
+      #
+      # @param cli_class [Class] The CLI module/class with a .start method
+      # @param args [Array<String>] Command line arguments
+      # @return [String] Standard output
+      #
+      # @example
+      #   output = invoke_cli_stdout(Ace::Search::CLI, ["version"])
+      #   assert_match(/\d+\.\d+/, output)
+      def invoke_cli_stdout(cli_class, args)
+        invoke_cli(cli_class, args)[:stdout]
+      end
+
+      # Assert CLI returns success (exit code 0)
+      #
+      # @param cli_class [Class] The CLI module/class with a .start method
+      # @param args [Array<String>] Command line arguments
+      # @param message [String, nil] Optional assertion message
+      #
+      # @example
+      #   assert_cli_success(Ace::Search::CLI, ["version"])
+      def assert_cli_success(cli_class, args, message = nil)
+        result = invoke_cli(cli_class, args)
+        assert_equal 0, result[:result],
+          message || "Expected CLI to return 0, got #{result[:result]}. stderr: #{result[:stderr]}"
+      end
+
+      # Assert CLI output matches pattern
+      #
+      # @param cli_class [Class] The CLI module/class with a .start method
+      # @param args [Array<String>] Command line arguments
+      # @param pattern [Regexp, String] Pattern to match against stdout
+      # @param message [String, nil] Optional assertion message
+      #
+      # @example
+      #   assert_cli_output_matches(Ace::Search::CLI, ["version"], /\d+\.\d+/)
+      def assert_cli_output_matches(cli_class, args, pattern, message = nil)
+        result = invoke_cli(cli_class, args)
+        assert_match pattern, result[:stdout],
+          message || "Expected stdout to match #{pattern.inspect}"
+      end
+    end
+  end
+end

data/lib/ace/test_support/config_helpers.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "tmpdir"
+
+module Ace
+  module TestSupport
+    # Helpers for config testing across all ace-* gems
+    module ConfigHelpers
+      # Execute block with test mode enabled
+      #
+      # This helper enables Ace::Support::Config test mode for the duration of the block,
+      # skipping filesystem searches and returning mock config instead.
+      #
+      # @param mock_config [Hash] Mock configuration data to return (default: {})
+      # @yield Block to execute with test mode enabled
+      # @return [Object] Result of the block
+      #
+      # @example Skip config filesystem access
+      #   with_test_config do
+      #     config = Ace::Support::Config.create.resolve
+      #     assert_equal({}, config.data)
+      #   end
+      #
+      # @example Provide mock config
+      #   with_test_config({ "key" => "value" }) do
+      #     config = Ace::Support::Config.create.resolve
+      #     assert_equal "value", config.get("key")
+      #   end
+      #
+      def with_test_config(mock_config = {})
+        require "ace/support/config"
+
+        original_test_mode = Ace::Support::Config.test_mode
+        original_mock = Ace::Support::Config.default_mock
+
+        Ace::Support::Config.test_mode = true
+        Ace::Support::Config.default_mock = mock_config
+
+        yield
+      ensure
+        Ace::Support::Config.test_mode = original_test_mode
+        Ace::Support::Config.default_mock = original_mock
+      end
+
+      # Execute block with real config (test mode disabled)
+      #
+      # This helper temporarily disables test mode for integration tests
+      # that need to test actual filesystem-based config loading.
+      #
+      # @yield Block to execute with real config
+      # @return [Object] Result of the block
+      #
+      # @example Run integration test with real config
+      #   with_real_config do
+      #     with_temp_config(".git" => "", ".ace" => { "config.yml" => "key: value" }) do
+      #       config = Ace::Support::Config.create.resolve
+      #       assert_equal "value", config.get("key")
+      #     end
+      #   end
+      #
+      def with_real_config
+        require "ace/support/config"
+
+        original_test_mode = Ace::Support::Config.test_mode
+
+        Ace::Support::Config.test_mode = false
+
+        yield
+      ensure
+        Ace::Support::Config.test_mode = original_test_mode
+      end
+
+      # Execute block with temporary config file
+      def with_config(path, content)
+        FileUtils.mkdir_p(File.dirname(path))
+
+        # Handle both Hash and String content
+        file_content = case content
+        when Hash
+          content.to_yaml
+        when String
+          content
+        else
+          raise ArgumentError, "Content must be Hash or String"
+        end
+
+        File.write(path, file_content)
+        yield
+      ensure
+        FileUtils.rm_f(path) if path && File.exist?(path)
+      end
+
+      # Execute block with temporary environment variables
+      def with_env(vars)
+        old_values = {}
+
+        vars.each do |key, value|
+          old_values[key] = ENV[key]
+          ENV[key] = value
+        end
+
+        yield
+      ensure
+        old_values.each do |key, value|
+          if value.nil?
+            ENV.delete(key)
+          else
+            ENV[key] = value
+          end
+        end
+      end
+
+      # Create multi-level config setup for any ace-* gem
+      def with_cascade_configs(gem_name = "core", configs = {})
+        paths = []
+        old_home = ENV["HOME"]
+        temp_home = nil
+
+        begin
+          # Create project config
+          if configs[:project]
+            project_path = "./.ace/#{gem_name}/config.yml"
+            FileUtils.mkdir_p(File.dirname(project_path))
+            File.write(project_path, configs[:project].to_yaml)
+            paths << project_path
+          end
+
+          # Create home config
+          if configs[:home]
+            temp_home = Dir.mktmpdir("ace-test-home")
+            ENV["HOME"] = temp_home
+            home_path = File.join(temp_home, ".ace", gem_name, "config.yml")
+            FileUtils.mkdir_p(File.dirname(home_path))
+            File.write(home_path, configs[:home].to_yaml)
+            paths << home_path
+          end
+
+          yield
+        ensure
+          ENV["HOME"] = old_home
+          FileUtils.rm_rf(temp_home) if temp_home && Dir.exist?(temp_home)
+          paths.each { |path| FileUtils.rm_f(path) if File.exist?(path) }
+        end
+      end
+
+      # Create sample config content
+      def sample_config(gem_name: "core", level: "default", custom: {})
+        base = {
+          "ace" => {
+            "level" => level,
+            gem_name => {
+              "version" => "1.0.0",
+              "environment" => "test"
+            }
+          }
+        }
+
+        deep_merge(base, custom)
+      end
+
+      # Create .env file content
+      def sample_env_content(vars = {})
+        default_vars = {
+          "ACE_ENV" => "test",
+          "ACE_DEBUG" => "false"
+        }
+
+        default_vars.merge(vars).map do |key, value|
+          "#{key}=#{value}"
+        end.join("\n")
+      end
+
+      # Assert config has expected structure
+      def assert_config_structure(config, expected)
+        assert_kind_of Hash, config
+
+        expected.each do |key, value|
+          assert config.key?(key), "Config missing key: #{key}"
+
+          if value.is_a?(Hash)
+            assert_config_structure(config[key], value)
+          else
+            assert_equal value, config[key], "Config value mismatch for #{key}"
+          end
+        end
+      end
+
+      # Assert config cascade precedence
+      def assert_precedence(resolver, key_path, expected_value, source_description)
+        config = resolver.resolve
+        actual = config.get(*key_path.split("."))
+
+        assert_equal expected_value, actual,
+          "Expected #{key_path} to be '#{expected_value}' from #{source_description}, got '#{actual}'"
+      end
+
+      # Create malformed YAML content
+      def malformed_yaml
+        "ace:\n  invalid: [\n    unclosed"
+      end
+
+      # Create valid but complex YAML
+      def complex_yaml
+        {
+          "ace" => {
+            "arrays" => [1, 2, 3],
+            "nested" => {
+              "deep" => {
+                "value" => "found"
+              }
+            },
+            "symbols" => {
+              "key" => :symbol_value
+            }
+          }
+        }.to_yaml
+      end
+
+      private
+
+      # Deep merge helper
+      def deep_merge(hash1, hash2)
+        hash1.merge(hash2) do |_key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge(old_val, new_val)
+          else
+            new_val
+          end
+        end
+      end
+    end
+  end
+end