test-map 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a6119ac2cd9cbbed7ab386e84db91d4af55abb17839e4eaed8e2db66aed8f10
+  data.tar.gz: 454388e46781b590ecc38d8b5bab9d6395f8b5db48c8b7f1241533fc519995c4
+SHA512:
+  metadata.gz: 8165ebf293a69de809d2c04cb496836d44b722ae52870bd13cb15688493066e65c7d9daa422bd62a86fd87cec871bfbe7acfec9ffdea26b44091e6d84b2d8936
+  data.tar.gz: 62f784cfb4a6968c8ccd481477cef3e4d5eec0dbcaa04bfec295514ea8b5ae1bc667c8f99d46d6aabf4c888bec3d23a4fce00a2bbbddd5b8cc6396a381121f68

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased] - yyyy-mm-dd
+
+Initial release.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Christoph Lipautz
+
+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,83 @@
+
+# Test-Map
+
+Track associated files of executed tests to optimize test execution on file
+changes.
+
+Test-Map results in a file that maps test files to the files they depend on.
+You can use this file to run only the tests that are affected by a file change.
+This is useful when you have a large test suite and want to optimize the time
+spent running tests. Submit a change request and only run tests that depend on
+what you changed. Optimizing in such way, the time spent waiting for CI to
+verify can be reduced to seconds.
+
+## Usage
+
+Add test-map to your Gemfile.
+
+```sh
+$ bundle add test-map
+```
+
+On demand you can adapt the configuration to your needs.
+
+```ruby
+TestMap::Configure.configure do |config|
+  config.logger = Logger.new($stdout) # default logs to dev/null
+  config.out_file = 'my-test-map.yml' # default is .test-map.yml
+  # defaults to [%r{^(vendor|test|spec)/}] }
+  config.exclude_patterns = [%r{^(libraries|testsuite)/}]
+  # register a custom rule to match new files; must implement `call(file)`;
+  # defaults to nil
+  config.natural_mapping = ->(file) { file.sub(%r{^library/}, 'test/') }
+end
+```
+
+### Minitest
+
+Include test-map in your test helper. Typically you want to include it
+conditionally so it only generates the test map when needed.
+
+```ruby
+# filename: test/test_helper.rb
+
+# Include test-map after minitest has been required
+require 'test_map' if ENV['TEST_MAP']
+```
+
+Run your tests with the `TEST_MAP` environment variable set.
+
+```sh
+$ TEST_MAP=1 bundle exec ruby -Itest test/models/user_test.rb
+# or
+$ TEST_MAP=1 bundle exec rake test
+```
+
+### Rspec
+
+Include test-map in your test helper. Typically you want to include it
+conditionally so it only generates the test map when needed.
+
+```ruby
+# filename: spec/spec_helper.rb
+require 'test_map' if ENV['TEST_MAP']
+```
+
+Run your tests with the `TEST_MAP` environment variable set.
+
+```sh
+$ TEST_MAP=1 bundle exec rspec
+```
+
+## Development
+
+```sh
+$ bundle install # install dependencies
+$ bundle exec rake # run testsuite
+$ bundle exec rubocop # run linter
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/unused/test-map).

data/lib/test_map/config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module TestMap
+  # Configuration for TestMap
+  class Config
+    def self.[](key) = config[key]
+    def self.config = @config ||= default_config
+    def self.configure = yield(config)
+
+    def self.default_config
+      { logger: Logger.new('/dev/null'), out_file: '.test-map.yml',
+        exclude_patterns: [%r{^(vendor)/}], natural_mapping: nil }
+    end
+  end
+end

data/lib/test_map/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module TestMap
+  # TraceInUseError is raised when a trace is already in use.
+  class TraceInUseError < StandardError
+    def self.default
+      new <<~MSG
+        Trace is already in use. Find for a second send of `#trace` and ensure
+        you only use one. Use `#results` to get the results.
+      MSG
+    end
+  end
+
+  # NotTracedError is raised when a trace has not been started.
+  class NotTracedError < StandardError
+    def self.default
+      new <<~MSG
+        Trace has not been started. Use `#trace` to start tracing.
+      MSG
+    end
+  end
+end

data/lib/test_map/file_recorder.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TestMap
+  # FileRecorder records files accessed during test execution.
+  class FileRecorder
+    def initialize = @files = []
+
+    def trace
+      raise TraceInUseError.default if @trace&.enabled?
+
+      @trace = TracePoint.new(:call) do |tp|
+        TestMap.logger.debug "#{tp.path}:#{tp.lineno}"
+        @files << tp.path
+      end.tap(&:enable)
+    end
+
+    def stop = @trace&.disable
+
+    # TODO: also add custom filters, e.g. for vendor directories
+    def results
+      raise NotTracedError.default unless @trace
+
+      @files.filter { _1.start_with? Dir.pwd }
+            .map { _1.sub("#{Dir.pwd}/", '') }
+            .then { Filter.call _1 }
+    end
+  end
+end

data/lib/test_map/filter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TestMap
+  # Filter skips files that are not part of the project.
+  class Filter
+    attr_writer :exclude_patterns
+
+    def self.call(files) = new.call(files)
+    def call(files) = files.reject { exclude? _1 }
+    def exclude_patterns = @exclude_patterns ||= Config[:exclude_patterns]
+    def exclude?(file) = exclude_patterns.any? { file.match? _1 }
+  end
+end

data/lib/test_map/mapping.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module TestMap
+  # Mapping looksup test files for changed files.
+  Mapping = Data.define(:map_file) do
+    def map = YAML.safe_load_file(map_file)
+
+    def lookup(*changed_files)
+      new_files = apply_natural_mapping(changed_files - map.keys)
+      map.values_at(*changed_files).concat(new_files).flatten.compact.uniq
+    end
+
+    def apply_natural_mapping(files)
+      files.map { |file| NaturalMapping.new(file).test_files }
+    end
+  end
+end

data/lib/test_map/natural_mapping.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module TestMap
+  # Natural mapping determines the test file for a given source file by
+  # applying common and configurable rules and transformation.
+  class NaturalMapping
+    CommonRule = Struct.new(:file) do
+      def self.call(file) = new(file).call
+
+      def call
+        if File.exist?('test')
+          transform('test')
+        elsif File.exist?('spec')
+          transform('spec')
+        end
+      end
+
+      def transform(type)
+        test_file = "#{File.basename(file, '.rb')}_#{type}.rb"
+        test_path = File.dirname(file).sub('app/', '')
+        test_path = nil if test_path == '.'
+        [type, test_path, test_file].compact.join('/')
+      end
+    end
+
+    attr_reader :file
+
+    def initialize(file) = @file = file
+    def test_files = Array(transform(file))
+
+    def transform(file)
+      self.class.registered_rules.each do |rule|
+        test_files = rule.call(file)
+
+        return test_files if test_files
+      end
+
+      nil
+    end
+
+    def self.registered_rules
+      @registered_rules ||= [
+        Config.config[:natural_mapping],
+        CommonRule
+      ].compact
+    end
+  end
+end

data/lib/test_map/plugins/minitest.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TestMap
+  module Plugins
+    # Minitest plugin for TestMap.
+    module Minitest
+      def self.included(_base)
+        TestMap.logger.info 'Registering hooks for Minitest'
+        ::Minitest.after_run do
+          result = TestMap.reporter.to_yaml
+          File.write "#{Dir.pwd}/#{Config.config[:out_file]}", result
+        end
+      end
+
+      def after_setup
+        @recorder = FileRecorder.new.tap(&:trace)
+
+        super
+      end
+
+      def before_teardown
+        super
+
+        @recorder.stop
+        TestMap.reporter.add @recorder.results
+      end
+    end
+  end
+end
+
+TestMap.logger.info 'Loading Minitest plugin'
+
+if defined?(Rails)
+  ActiveSupport::TestCase.include TestMap::Plugins::Minitest
+else
+  Minitest::Test.include TestMap::Plugins::Minitest
+end

data/lib/test_map/plugins/rspec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+TestMap.logger.info 'Loading RSpec plugin'
+
+RSpec.configure do |config|
+  config.around(:example) do |example|
+    # path = example.metadata[:example_group][:file_path]
+    recorder = TestMap::FileRecorder.new.tap(&:trace)
+    example.run
+  ensure
+    recorder.stop
+    TestMap.reporter.add recorder.results
+  end
+
+  config.after(:suite) do
+    result = TestMap.reporter.to_yaml
+    File.write "#{Dir.pwd}/#{TestMap::Config.config[:out_file]}", result
+  end
+end

data/lib/test_map/report.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module TestMap
+  # Report keeps track of associated files to test execution.
+  class Report
+    def initialize = @results = Hash.new { Set.new }
+
+    def add(files)
+      test_file, *associated_files = files
+      TestMap.logger.info "Adding #{test_file} with #{associated_files}"
+      associated_files.each do |file|
+        @results[file] = @results[file] << test_file
+      end
+    end
+
+    def results = @results.transform_values { _1.to_a.sort }.sort.to_h
+    def to_yaml = results.to_yaml
+  end
+end

data/lib/test_map/test_task.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'mapping'
+require 'rake/testtask'
+require 'minitest'
+require 'minitest/unit'
+
+module TestMap
+  # TestTask is a rake helper class.
+  class TestTask < Rake::TaskLib
+    # Error for unknown test task adapter.
+    class UnknownAdapterError < StandardError; end
+
+    def initialize(name) # rubocop:disable Lint/MissingSuper
+      @name = name
+    end
+
+    # Adapter for minitest test task.
+    class MinitestTask < Minitest::TestTask
+      def call = ruby(make_test_cmd, verbose: false)
+
+      def files=(test_files)
+        self.test_globs = test_files
+      end
+    end
+
+    # Adapter for rspec test task
+    class RSpecTask
+      attr_accessor :files
+
+      def call = `rspec #{files.join(' ')}`
+    end
+
+    def self.create(name = :test) = new(name).define
+
+    def define
+      namespace @name do
+        desc 'Run tests for changed files'
+        task :changes do
+          out_file = "#{Dir.pwd}/.test-map.yml"
+          test_files = Mapping.new(out_file).lookup(*ARGV[1..])
+
+          # puts "Running tests #{test_files.join(' ')}"
+          test_task.files = test_files
+          test_task.call
+        end
+      end
+    end
+
+    def test_task = @test_task ||= build_test_task
+
+    def build_test_task
+      if defined?(Minitest)
+        return MinitestTask.new
+      elsif defined?(RSpec)
+        return RSpecTask.new
+      end
+
+      raise UnknownAdapterError, 'No test task adapter found'
+    end
+  end
+end

data/lib/test_map/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TestMap
+  VERSION = '0.1.0'
+end

data/lib/test_map.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'test_map/config'
+require_relative 'test_map/version'
+require_relative 'test_map/errors'
+require_relative 'test_map/filter'
+require_relative 'test_map/report'
+require_relative 'test_map/file_recorder'
+require_relative 'test_map/natural_mapping'
+require_relative 'test_map/mapping'
+
+# TestMap records associated files to test execution.
+module TestMap
+  def self.reporter = @reporter ||= Report.new
+  def self.logger = Config.config[:logger]
+end
+
+# Load plugins for supported test frameworks.
+require_relative 'test_map/plugins/minitest' if defined?(Minitest)
+require_relative 'test_map/plugins/rspec' if defined?(RSpec)

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: test-map
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Christoph Lipautz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-09-22 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Track files that are covered by test files to execute only the necessary
+  tests.
+email:
+- christoph@lipautz.org
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/test_map.rb
+- lib/test_map/config.rb
+- lib/test_map/errors.rb
+- lib/test_map/file_recorder.rb
+- lib/test_map/filter.rb
+- lib/test_map/mapping.rb
+- lib/test_map/natural_mapping.rb
+- lib/test_map/plugins/minitest.rb
+- lib/test_map/plugins/rspec.rb
+- lib/test_map/report.rb
+- lib/test_map/test_task.rb
+- lib/test_map/version.rb
+homepage: https://github.com/unused/test-map
+licenses: []
+metadata:
+  homepage_uri: https://github.com/unused/test-map
+  source_code_uri: https://github.com/unused/test-map
+  changelog_uri: https://github.com/unused/test-map/main/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key: 
+specification_version: 4
+summary: Track associated files of tests.
+test_files: []