fastlane-plugin-stream_actions 0.4.10 → 0.4.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2401c759c842685fbbb27e25fba273091eff05627873dc3f245a2692ac729986
-  data.tar.gz: 535b9fdb380ecae53c5ca3c39f69ad5f70ee481d0c8c65f088b3992914e53efa
+  metadata.gz: 7e20315e989110210371734616854eb1cf055d2318fe8c1c7031ee5642eb95cf
+  data.tar.gz: 87fab4f22f00b8771fdede017075a4df012942c24baae580613313e781e55745
 SHA512:
-  metadata.gz: a2b45995454c839f0451745d3ca98da00f96ac09f862bc20669b96cf2c4ebf87973041bc2fbf4b8f16cd417d3db8b6abbbc61e6d75a88e4440f8b008804bff75
-  data.tar.gz: e1a9de8fdf353ff9138031d5ee066004942e86de5da07d6a159496919c4d34592a0b7a0f73d5bfb7b43caabf9971cd6a8428358a2e676c3365fa0af26bc85960
+  metadata.gz: cf84b704871864755de8317c4e0e9aef2ffd38275f6a8ab8903e3e1f7289c7fdf7563e77aed2aa27f2a61e26621f84c9a9587d659683ae86b1b8550134ec9288
+  data.tar.gz: e784f17eb5d31bb15d53209d69e58135a07f7d87d3a6ea03461ca8b627e63da6cda99b80655a97f62bba9417e8d7c49496edc8c61314ada0eeca797808ed4fa5

data/lib/fastlane/plugin/stream_actions/actions/build_test_coverage_map.rb

@@ -0,0 +1,243 @@
+require 'json'
+require 'open3'
+require 'set'
+require 'time'
+
+module Fastlane
+  module Actions
+    class BuildTestCoverageMapAction < Action
+      def self.run(params)
+        source_root = File.expand_path(params[:source_root] || Dir.pwd)
+        test_dirs = Dir.glob(File.join(params[:coverage_dir], '*', '*')).select { |dir| File.directory?(dir) }
+        UI.user_error!("No per-test coverage found in '#{params[:coverage_dir]}'") if test_dirs.empty?
+
+        binaries = params[:binaries].select { |binary| File.exist?(binary) }
+        UI.user_error!('None of the instrumented binaries exist') if binaries.empty?
+
+        UI.message("Building the coverage map of #{test_dirs.size} tests ⌛️")
+        sources = []
+        tests = {}
+        lock = Mutex.new
+        queue = Queue.new
+        test_dirs.each { |dir| queue << dir }
+
+        workers = Array.new([params[:jobs], test_dirs.size].min) do
+          Thread.new do
+            until queue.empty?
+              dir = begin
+                queue.pop(true)
+              rescue ThreadError
+                break
+              end
+              test = dir.split('/').last(2).join('/')
+              report = coverage_report(dir, binaries)
+              next if report.nil?
+
+              lock.synchronize do
+                sources |= report[:all].map { |file| relative_path(file, source_root) }.compact
+                tests[test] = report[:covered].map { |file| relative_path(file, source_root) }.compact
+              end
+            end
+          end
+        end
+        workers.each(&:join)
+
+        carry_over_failed_tests(tests, sources, params) unless params[:failed_tests].to_a.empty?
+        drop_untracked(tests, sources, source_root)
+
+        map = {
+          'version' => Helper::TestCoverageMapHelper::MAP_VERSION,
+          'generated_at' => Time.now.utc.iso8601,
+          'commit' => params[:commit],
+          'sources' => sources.sort,
+          'tests' => tests.sort.to_h
+        }
+        write(map, params[:output_path])
+        UI.success("Coverage map of #{tests.size} tests and #{map['sources'].size} sources saved to #{params[:output_path]}")
+        map
+      end
+
+      # Returns the instrumented files (`all`) and the files with at least one executed line (`covered`).
+      def self.coverage_report(dir, binaries)
+        profiles = Dir.glob(File.join(dir, '**', '*.profraw'))
+        if profiles.empty?
+          UI.important("No profiles in #{dir}, skipping")
+          return nil
+        end
+
+        profdata = File.join(dir, 'merged.profdata')
+        _, err, status = Open3.capture3('xcrun', 'llvm-profdata', 'merge', '-sparse', *profiles, '-o', profdata)
+        unless status.success?
+          UI.important("Could not merge the profiles in #{dir}: #{err}")
+          return nil
+        end
+
+        objects = binaries.drop(1).flat_map { |binary| ['-object', binary] }
+        out, err, status = Open3.capture3(
+          'xcrun', 'llvm-cov', 'export', '-format=text', '-summary-only',
+          "-instr-profile=#{profdata}", binaries.first, *objects
+        )
+        unless status.success?
+          UI.important("Could not export the coverage of #{dir}: #{err}")
+          return nil
+        end
+
+        files = JSON.parse(out).fetch('data').flat_map { |data| data.fetch('files') }
+        {
+          all: files.map { |file| file['filename'] },
+          covered: files.select { |file| file.dig('summary', 'lines', 'covered').to_i.positive? }.map { |file| file['filename'] }
+        }
+      end
+
+      # A failed test stops early, so its fresh coverage can miss code it normally runs.
+      def self.carry_over_failed_tests(tests, sources, params)
+        path = params[:previous_map]
+        if path.nil? && params[:previous_map_artifact]
+          path = Helper::TestCoverageMapHelper.download_map(
+            coverage_map_artifact: params[:previous_map_artifact],
+            coverage_map_branch: params[:previous_map_branch],
+            github_repository: params[:github_repository]
+          )
+        end
+        return if path.nil? || !File.exist?(path)
+
+        previous = Helper::TestCoverageMapHelper.read_map(path)
+        params[:failed_tests].to_a.each do |failed_test|
+          test = failed_test.split('/').last(2).join('/')
+          previous_files = previous['tests'][test]
+          next if previous_files.nil?
+
+          tests[test] = (tests[test].to_a | previous_files)
+          sources.concat(previous_files - sources)
+          UI.message("Kept the previous coverage of the failed #{test}")
+        end
+      end
+
+      # Keeps sources the repository tracks, dropping e.g. package checkouts cloned inside it.
+      def self.drop_untracked(tests, sources, source_root)
+        tracked = Helper::TestCoverageMapHelper.command('git', '-C', source_root, 'ls-files').split("\n").to_set
+        sources.select! { |file| tracked.include?(file) }
+        tests.each_value { |files| files.select! { |file| tracked.include?(file) } }
+      rescue StandardError => e
+        UI.important("Could not list the tracked files, keeping every source: #{e.message}")
+      end
+
+      def self.relative_path(file, source_root)
+        return nil unless file.start_with?("#{source_root}/")
+
+        file.delete_prefix("#{source_root}/")
+      end
+
+      # Stores file indices instead of paths, which keeps the map an order of magnitude smaller.
+      def self.write(map, path)
+        index = map['sources'].each_with_index.to_h
+        compact = map.merge('tests' => map['tests'].transform_values { |files| files.map { |file| index.fetch(file) }.sort })
+        File.write(path, JSON.generate(compact))
+      end
+
+      #####################################################
+      # @!group Documentation
+      #####################################################
+
+      def self.description
+        'Builds a map of which source files every test executes, from per-test LLVM coverage profiles'
+      end
+
+      def self.details
+        <<~DETAILS
+          Expects one folder per test, `<coverage_dir>/<TestClass>/<testMethod>/`, holding the `.profraw` files
+          the app wrote while that test ran (e.g. via `LLVM_PROFILE_FILE=<dir>/<TestClass>/<testMethod>/%m_%p%c.profraw`
+          in the app's launch environment). Each folder is merged with `llvm-profdata` and exported with `llvm-cov`
+          against the instrumented `binaries`. The resulting JSON map feeds `select_impacted_tests`.
+        DETAILS
+      end
+
+      def self.return_value
+        'Hash with `version`, `generated_at`, `commit`, `sources` (every instrumented file) and `tests` (`Class/test` => covered files).'
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(
+            key: :coverage_dir,
+            description: 'Folder with per-test profiles, laid out as <TestClass>/<testMethod>/*.profraw',
+            verify_block: proc { |path| UI.user_error!("Coverage folder '#{path}' does not exist") unless File.directory?(path) }
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :binaries,
+            description: 'Instrumented binaries the profiles belong to, e.g. the app executable (or its .debug.dylib) and every SDK framework',
+            type: Array
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :source_root,
+            description: 'Repository root, the current directory by default (fastlane runs actions from the repository root). ' \
+                         'Paths in the map are relative to it, and files outside it (e.g. SPM checkouts) are dropped',
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :output_path,
+            description: 'Where to write the JSON map'
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :commit,
+            description: 'Commit the map was built from',
+            optional: true,
+            default_value: ENV['GITHUB_SHA']
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :previous_map,
+            description: 'Previous map to take the coverage of failed_tests from, as a failed test stops before running all of its code',
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :previous_map_artifact,
+            description: 'GitHub Actions artifact to download the previous map from when previous_map is not set',
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :previous_map_branch,
+            description: 'Branch whose artifact to download',
+            default_value: 'develop'
+          ),
+          FastlaneCore::ConfigItem.new(
+            env_name: 'GITHUB_REPOSITORY',
+            key: :github_repository,
+            description: 'Repository in "owner/repo" form, for downloading the artifact',
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :failed_tests,
+            description: 'Tests that failed in this run, as Class/test or Target/Class/test',
+            type: Array,
+            optional: true,
+            default_value: []
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :jobs,
+            description: 'How many tests to process in parallel',
+            type: Integer,
+            default_value: 8
+          )
+        ]
+      end
+
+      def self.example_code
+        [
+          'build_test_coverage_map(
+            coverage_dir: "test_output/coverage",
+            binaries: ["App.app/App.debug.dylib", "App.app/Frameworks/SDK.framework/SDK"],
+            output_path: "test_output/e2e_coverage_map.json"
+          )'
+        ]
+      end
+
+      def self.category
+        :testing
+      end
+
+      def self.is_supported?(platform)
+        [:ios, :mac].include?(platform)
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/stream_actions/actions/select_impacted_tests.rb

@@ -0,0 +1,369 @@
+require 'json'
+require 'set'
+require 'time'
+
+module Fastlane
+  module Actions
+    class SelectImpactedTestsAction < Action
+      CODE_EXTENSIONS = %w[.swift .m .mm .h .kt .java .dart .js .jsx .ts .tsx].freeze
+      MODIFIERS = '(?:(?:public|open|internal|fileprivate|private|final|indirect|nonisolated|data|sealed|abstract|export|default)\\s+)*'
+      DECLARATION = /^\s*(?:@\w+(?:\([^)\n]*\))?\s+)*#{MODIFIERS}(?:class|struct|enum|protocol|actor|typealias|extension|interface|object)\s+([A-Za-z_]\w*)/.freeze
+
+      def self.run(params)
+        source_root = File.expand_path(params[:source_root] || Dir.pwd)
+        all_tests = params[:all_tests]
+        selection = Dir.chdir(source_root) { select(params, all_tests, source_root) }
+
+        if selection['run_all']
+          UI.important("Running all #{all_tests.size} tests: #{selection['reasons'].join('; ')}")
+        else
+          UI.important("Running #{selection['tests'].size} of #{all_tests.size} tests")
+          selection['reasons'].each { |reason| UI.message("  #{reason}") }
+        end
+        File.write(params[:output_path], JSON.pretty_generate(selection)) if params[:output_path]
+        selection
+      end
+
+      def self.select(params, all_tests, source_root)
+        changes = changed_files(params)
+        return run_all(all_tests, 'the changed files are unknown') if changes.nil?
+        return selection(all_tests, [], ['no changed files']) if changes.empty?
+
+        forcing = changes.keys.find { |file| matches_any?(file, params[:run_all_paths]) && !only_ignored_lines?(file, params) }
+        return run_all(all_tests, "#{forcing} affects every test") if forcing
+
+        map = load_map(params)
+        return run_all(all_tests, 'no coverage map') if map.nil?
+
+        age_days = (Time.now.utc - Time.parse(map['generated_at'])) / 86_400
+        return run_all(all_tests, "the coverage map is #{age_days.round(1)} days old") if age_days > params[:max_map_age_days]
+
+        tests_by_file = Hash.new { |hash, key| hash[key] = [] }
+        map['tests'].each { |test, files| files.each { |file| tests_by_file[file] << test } }
+        known_sources = map['sources'].to_set
+        mapped_count = map['tests'].size
+
+        selected = []
+        reasons = []
+        changes.each do |file, status|
+          if matches_any?(file, params[:ignore_paths])
+            next
+          elsif matches_any?(file, params[:test_paths])
+            classes = test_classes(file, source_root)
+            tests = all_tests.select { |id| classes.include?(test_key(id).split('/').first) }
+            selected.concat(tests)
+            reasons << "#{file}: #{tests.size} tests of #{classes.join(', ')}"
+          elsif known_sources.include?(file)
+            tests = tests_by_file[file]
+            selected.concat(impacted(tests, all_tests, mapped_count, params))
+            reasons << "#{file}: #{describe(tests, mapped_count, params)}"
+          elsif matches_any?(file, params[:source_paths])
+            return run_all(all_tests, "#{file} is not in the coverage map") unless CODE_EXTENSIONS.include?(File.extname(file))
+
+            if status == 'A' || status == 'D'
+              reasons << "#{file}: #{status == 'A' ? 'added' : 'deleted'}, so the files using it changed too"
+              next
+            end
+
+            # Declaration-only files (models, protocols, constants) have no executable regions, so coverage
+            # never lists them. Their declarations still matter, e.g. a Codable key, so run the tests of the
+            # mapped files that reference the declared types.
+            names = declared_names(file, source_root, params)
+            return run_all(all_tests, "#{file} is not in the coverage map and declares no types") if names.empty?
+
+            users = referencing_files(names, known_sources - [file], source_root)
+            tests = users.flat_map { |user| tests_by_file[user] }.uniq
+            selected.concat(impacted(tests, all_tests, mapped_count, params))
+            reasons << "#{file}: #{describe(tests, mapped_count, params)} of the #{users.size} mapped files using #{names.join(', ')}"
+          end
+        end
+
+        mapped = map['tests'].keys.to_set
+        unmapped = all_tests.reject { |id| mapped.include?(test_key(id)) }
+        unless unmapped.empty?
+          selected.concat(unmapped)
+          reasons << "#{unmapped.size} tests that are not in the coverage map yet"
+        end
+
+        selection(all_tests, selected.uniq, reasons)
+      end
+
+      # Returns { path => git status letter }, or nil when the diff cannot be computed.
+      def self.changed_files(params)
+        return params[:changed_files].map { |file| [file, 'M'] }.to_h if params[:changed_files]
+
+        range = diff_range(params)
+        if range.nil?
+          UI.important('Pass changed_files or diff_base, or run on a pull request merge commit')
+          return nil
+        end
+
+        output = Helper::TestCoverageMapHelper.command('git', 'diff', '--name-status', '--no-renames', range)
+        output.split("\n").map do |line|
+          status, path = line.split("\t", 2)
+          [path, status[0]]
+        end.to_h
+      rescue StandardError => e
+        UI.important("Could not list the changed files: #{e.message}")
+        nil
+      end
+
+      def self.diff_range(params)
+        base = params[:diff_base]
+        if base.nil?
+          parents = Helper::TestCoverageMapHelper.command('git', 'rev-list', '--parents', '-n', '1', 'HEAD').split
+          # GitHub checks out pull requests as a merge commit whose first parent is the base branch tip.
+          base = 'HEAD^1' if parents.size == 3
+        end
+        base.nil? ? nil : "#{base}...#{params[:diff_head]}"
+      end
+
+      # True when every added or removed line of the file matches one of its ignored_diff_lines patterns.
+      def self.only_ignored_lines?(file, params)
+        patterns = params[:ignored_diff_lines].to_h.find { |path, _| matches_any?(file, [path]) }&.last
+        return false if patterns.nil? || params[:changed_files]
+
+        regexes = patterns.map { |pattern| Regexp.new(pattern) }
+        lines = Helper::TestCoverageMapHelper.command('git', 'diff', '-U0', diff_range(params), '--', file).lines.map(&:chomp)
+        changed = lines.select { |line| line.match?(/^[+-]/) && !line.match?(/^(\+\+\+|---) /) }.map { |line| line[1..-1] }
+        changed.all? { |line| regexes.any? { |regex| line.match?(regex) } }
+      rescue StandardError => e
+        UI.important("Could not read the diff of #{file}: #{e.message}")
+        false
+      end
+
+      def self.load_map(params)
+        path = params[:coverage_map]
+        path = Helper::TestCoverageMapHelper.download_map(params) if (path.nil? || !File.exist?(path)) && params[:coverage_map_artifact]
+        return nil if path.nil? || !File.exist?(path)
+
+        Helper::TestCoverageMapHelper.read_map(path)
+      rescue StandardError => e
+        UI.important("Could not read the coverage map: #{e.message}")
+        nil
+      end
+
+      def self.test_classes(file, source_root)
+        path = File.join(source_root, file)
+        classes = File.exist?(path) ? File.read(path).scan(/^\s*(?:(?:public|open|final|internal)\s+)*class\s+(\w+)/).flatten : []
+        classes.empty? ? [File.basename(file, '.*')] : classes
+      end
+
+      # Code nearly every test runs (app start, login, the main screen) would select everything. With
+      # hot_test_ratio such a change runs one test per class instead, leaving the rest to the full nightly run.
+      def self.impacted(tests, all_tests, mapped_count, params)
+        return smoke_tests(all_tests) if hot?(tests, mapped_count, params)
+
+        all_tests.select { |id| tests.include?(test_key(id)) }
+      end
+
+      def self.hot?(tests, mapped_count, params)
+        params[:hot_test_ratio] && mapped_count.positive? && tests.size >= params[:hot_test_ratio] * mapped_count
+      end
+
+      def self.smoke_tests(all_tests)
+        all_tests.group_by { |id| test_key(id).split('/').first }.values.map(&:first)
+      end
+
+      def self.describe(tests, mapped_count, params)
+        hot?(tests, mapped_count, params) ? "run by #{tests.size} tests, so one test per class" : "#{tests.size} tests"
+      end
+
+      def self.declared_names(file, source_root, params)
+        content = begin
+          params[:changed_files] ? File.read(File.join(source_root, file)) : Helper::TestCoverageMapHelper.command('git', 'show', "#{params[:diff_head]}:#{file}")
+        rescue StandardError
+          ''
+        end
+        content.scan(DECLARATION).flatten.uniq
+      end
+
+      def self.referencing_files(names, files, source_root)
+        pattern = /\b(?:#{names.map { |name| Regexp.escape(name) }.join('|')})\b/
+        files.select do |file|
+          path = File.join(source_root, file)
+          File.exist?(path) && File.read(path).match?(pattern)
+        end
+      end
+
+      def self.matches_any?(file, patterns)
+        patterns.to_a.any? do |pattern|
+          if pattern.include?('*')
+            File.fnmatch?(pattern, file, File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH)
+          else
+            file == pattern || file.start_with?(pattern.end_with?('/') ? pattern : "#{pattern}/")
+          end
+        end
+      end
+
+      # Target/Class/test -> Class/test, the key the coverage map uses.
+      def self.test_key(id)
+        id.split('/').last(2).join('/')
+      end
+
+      def self.run_all(all_tests, reason)
+        selection(all_tests, all_tests, [reason], run_all: true)
+      end
+
+      def self.selection(all_tests, tests, reasons, run_all: false)
+        order = all_tests.each_with_index.to_h
+        { 'run_all' => run_all, 'tests' => tests.sort_by { |id| order.fetch(id) }, 'reasons' => reasons }
+      end
+
+      #####################################################
+      # @!group Documentation
+      #####################################################
+
+      def self.description
+        'Selects the tests a change can affect, using a per-test coverage map'
+      end
+
+      def self.details
+        <<~DETAILS
+          Intersects the changed files with a coverage map from `build_test_coverage_map` (or any producer that
+          writes the same JSON) and returns the tests that executed any of them. Falls back to all tests whenever
+          it cannot prove a test is unaffected:
+          - the changed files or the map are unavailable, or the map is older than `max_map_age_days`;
+          - a changed file matches `run_all_paths` (test infrastructure, build settings, CI config);
+          - a changed file under `source_paths` is not in the map and is not code (e.g. resources).
+          A changed code file that is not in the map and was not added or deleted is declaration-only (coverage
+          lists only files with executable code): it selects the tests of the mapped files that reference the
+          types it declares.
+          A changed file under `test_paths` selects every test of the classes it declares, and tests that are not
+          in the map yet (added after it was built) always run. Files outside all paths are ignored.
+          With `hot_test_ratio`, a file that (nearly) every test runs selects one test per class instead of all tests;
+          use it only when a full run on the base branch catches what that sample misses.
+        DETAILS
+      end
+
+      def self.return_value
+        'Hash with `run_all` (Boolean), `tests` (subset of all_tests, in their order) and `reasons` (Array of String).'
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(
+            key: :all_tests,
+            description: 'Every test identifier that could run, e.g. Target/Class/test from retrieve_xctest_names',
+            type: Array
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :coverage_map,
+            description: 'Path to the coverage map JSON',
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :coverage_map_artifact,
+            description: 'GitHub Actions artifact to download the map from when coverage_map does not exist',
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :coverage_map_branch,
+            description: 'Branch whose artifact to download',
+            default_value: 'develop'
+          ),
+          FastlaneCore::ConfigItem.new(
+            env_name: 'GITHUB_REPOSITORY',
+            key: :github_repository,
+            description: 'Repository in "owner/repo" form, for downloading the artifact',
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :changed_files,
+            description: 'Changed file paths relative to source_root. When nil, they come from `git diff diff_base...diff_head`',
+            type: Array,
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :diff_base,
+            description: 'Git revision to diff against. Defaults to the first parent of a pull request merge commit',
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :diff_head,
+            description: 'Git revision with the changes',
+            default_value: 'HEAD'
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :source_paths,
+            description: 'Path prefixes or globs of the code under test. Unmapped changes here run all tests',
+            type: Array,
+            default_value: []
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :test_paths,
+            description: 'Path prefixes or globs of the test classes. A change here runs the tests of the classes in the file',
+            type: Array,
+            default_value: []
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :ignore_paths,
+            description: 'Path prefixes or globs that never affect tests, e.g. code generation configs inside source_paths',
+            type: Array,
+            default_value: []
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :run_all_paths,
+            description: 'Path prefixes or globs whose change runs all tests, e.g. test helpers, project files, CI config',
+            type: Array,
+            default_value: []
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :ignored_diff_lines,
+            description: 'Per run_all path or glob, regexes of changed lines that do not affect tests, ' \
+                         'e.g. file membership in project.pbxproj. The path runs all tests only if another line changed. ' \
+                         'Needs the git diff, so it does not apply to changed_files. Defaults to target membership ' \
+                         'edits in **/*.pbxproj; passing a hash replaces the default',
+            type: Hash,
+            default_value: { '**/*.pbxproj' => Helper::TestCoverageMapHelper::XCODE_PROJECT_IGNORED_LINES }
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :hot_test_ratio,
+            description: 'When a changed file is run by at least this share of the mapped tests (e.g. 0.9), select one ' \
+                         'test per class for it instead of all of them. nil selects every test that runs the file',
+            type: Float,
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :max_map_age_days,
+            description: 'Run all tests when the map is older than this',
+            type: Float,
+            default_value: 7.0
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :source_root,
+            description: 'Repository root that changed file paths are relative to, the current directory by default ' \
+                         '(fastlane runs actions from the repository root)',
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :output_path,
+            description: 'Where to write the selection as JSON',
+            optional: true
+          )
+        ]
+      end
+
+      def self.example_code
+        [
+          'selection = select_impacted_tests(
+            all_tests: retrieve_xctest_names(xctestrun: xctestrun).values.flatten,
+            coverage_map_artifact: "e2e-coverage-map",
+            source_paths: ["Sources"],
+            test_paths: ["UITests/Tests"],
+            run_all_paths: ["UITests/Robots", "Package.swift", ".github/workflows"]
+          )
+          scan(only_testing: selection["tests"]) unless selection["tests"].empty?'
+        ]
+      end
+
+      def self.category
+        :testing
+      end
+
+      def self.is_supported?(platform)
+        true
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/stream_actions/helper/test_coverage_map_helper.rb

@@ -0,0 +1,57 @@
+require 'json'
+require 'open3'
+require 'tmpdir'
+
+module Fastlane
+  module Helper
+    # Reads, writes and downloads the per-test coverage maps of build_test_coverage_map and select_impacted_tests.
+    class TestCoverageMapHelper
+      # Changed project.pbxproj lines that only move files in and out of targets; the files themselves are diffed and
+      # mapped. List items (`ID /* Name */,`) also cover packageProductDependencies and target dependencies.
+      XCODE_PROJECT_IGNORED_LINES = [
+        '/\* .+ \*/,?$',
+        '/\* .+ \*/ = \{isa = PBX(BuildFile|FileReference); ',
+        '/\* Exceptions for .+ \*/ = \{$',
+        '^\s*isa = PBXFileSystemSynchronized\w*ExceptionSet;$',
+        '^\s*(buildPhase|target) = \w+ /\* .+ \*/;$',
+        '^\s*(children|exceptions|files|membershipExceptions) = \($',
+        '^\s*[^=]+\.\w+,$',
+        '^\s*\)?;?$',
+        '^\s*\};$'
+      ].freeze
+
+      MAP_VERSION = 1
+
+      # Downloads the newest unexpired artifact with this name produced on coverage_map_branch.
+      def self.download_map(params)
+        repo = params[:github_repository]
+        query = ".artifacts | map(select(.expired | not) | select(.workflow_run.head_branch == \"#{params[:coverage_map_branch]}\")) " \
+                '| sort_by(.created_at) | last | .workflow_run.id // empty'
+        run_id = command('gh', 'api', "repos/#{repo}/actions/artifacts?name=#{params[:coverage_map_artifact]}&per_page=100", '-q', query).strip
+        return nil if run_id.empty?
+
+        dir = Dir.mktmpdir('coverage-map')
+        command('gh', 'run', 'download', run_id, '--repo', repo, '--name', params[:coverage_map_artifact], '--dir', dir)
+        Dir.glob(File.join(dir, '**', '*.json')).first
+      rescue StandardError => e
+        UI.important("Could not download the coverage map: #{e.message}")
+        nil
+      end
+
+      def self.command(*args)
+        output, status = Open3.capture2e(*args)
+        raise "`#{args.join(' ')}` failed: #{output}" unless status.success?
+
+        output
+      end
+
+      def self.read_map(path)
+        map = JSON.parse(File.read(path))
+        UI.user_error!("Unsupported coverage map version #{map['version']}") unless map['version'] == MAP_VERSION
+
+        sources = map['sources']
+        map.merge('tests' => map['tests'].transform_values { |indices| indices.map { |i| sources.fetch(i) } })
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/stream_actions/version.rb

@@ -1,5 +1,5 @@
 module Fastlane
   module StreamActions
-    VERSION = '0.4.10'
+    VERSION = '0.4.12'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fastlane-plugin-stream_actions
 version: !ruby/object:Gem::Version
-  version: 0.4.10
+  version: 0.4.12
 platform: ruby
 authors:
 - GetStream
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: xctest_list
@@ -233,6 +233,7 @@ files:
 - lib/fastlane/plugin/stream_actions/actions/allure_create_testcase.rb
 - lib/fastlane/plugin/stream_actions/actions/allure_run_testplan.rb
 - lib/fastlane/plugin/stream_actions/actions/build_app_for_ios_simulator.rb
+- lib/fastlane/plugin/stream_actions/actions/build_test_coverage_map.rb
 - lib/fastlane/plugin/stream_actions/actions/check_unsafe_flags.rb
 - lib/fastlane/plugin/stream_actions/actions/core_version.rb
 - lib/fastlane/plugin/stream_actions/actions/current_branch.rb
@@ -252,6 +253,7 @@ files:
 - lib/fastlane/plugin/stream_actions/actions/read_changelog.rb
 - lib/fastlane/plugin/stream_actions/actions/release_ios_sdk.rb
 - lib/fastlane/plugin/stream_actions/actions/retrieve_xctest_names.rb
+- lib/fastlane/plugin/stream_actions/actions/select_impacted_tests.rb
 - lib/fastlane/plugin/stream_actions/actions/select_xcode.rb
 - lib/fastlane/plugin/stream_actions/actions/setup_git_config.rb
 - lib/fastlane/plugin/stream_actions/actions/show_detailed_sdk_size.rb
@@ -263,6 +265,7 @@ files:
 - lib/fastlane/plugin/stream_actions/actions/update_sdk_size_in_readme.rb
 - lib/fastlane/plugin/stream_actions/actions/update_testplan.rb
 - lib/fastlane/plugin/stream_actions/actions/wait_android_emu_idle.rb
+- lib/fastlane/plugin/stream_actions/helper/test_coverage_map_helper.rb
 - lib/fastlane/plugin/stream_actions/version.rb
 homepage: https://github.com/GetStream/fastlane-plugin-stream_actions
 licenses: []