gitlab_quality-test_tooling 3.0.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f037a73b3fd4a445324a37084915ea2d020475cca6f4e3b1d23045f290351082
-  data.tar.gz: e32bc045856df09004e725b9b84317c74ffb66b59ed640b078e292f46a3ff565
+  metadata.gz: 32b52c2177aaf57f1ccf6a2bb922fd47e267b251ce74921c356f9631252051da
+  data.tar.gz: 8930c0fb427f3a946cd99902a230bcf90c48a051c9ffa1d19fb10a487107d231
 SHA512:
-  metadata.gz: 400c1e51bf57a3f10cdb36c083444153326da8710edd828839881867aed4d9282da4b21fa16357f49bb498ac48199dda888e422e1ddf4f5453769cb5bdc92211
-  data.tar.gz: cc071d0ca3c54a0d3408f6fc91165348c403ab5109c473d7bc518701a17f90d992f02139614dfb99fd53cac7e0ffef688241c7c232cf373344269ffe3e8b4436
+  metadata.gz: f265a7b7c74d4ef36e06c53a945b96ab066a4304acd0e6c439cf10afee6d0483de9253ca9290b279db7ec3c1d2323146da3aea8cf92aa57d4d1914c9c1479b1f
+  data.tar.gz: b983b542d66e9ac5b5775dd97b80ce6b464a618a5adf573f18613014dcfecc86555fc8b7d20e32b33b41b23ce9be255811cc276a50a1ee7945f0e4062deb15cf

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    gitlab_quality-test_tooling (3.0.0)
-      activesupport (>= 7.0, < 7.3)
+    gitlab_quality-test_tooling (3.3.0)
+      activesupport (>= 7.0)
       amatch (~> 0.4.1)
       fog-google (~> 1.24, >= 1.24.1)
       gitlab (>= 4.19, < 7.0)

data/exe/test-coverage

@@ -3,21 +3,26 @@
 
 require "optparse"
 require "uri"
+require "yaml"
 
 require_relative "../lib/gitlab_quality/test_tooling"
 
 require_relative '../lib/gitlab_quality/test_tooling/code_coverage/category_owners'
 require_relative '../lib/gitlab_quality/test_tooling/code_coverage/click_house/category_owners_table'
 require_relative '../lib/gitlab_quality/test_tooling/code_coverage/click_house/coverage_metrics_table'
+require_relative '../lib/gitlab_quality/test_tooling/code_coverage/click_house/test_file_mappings_table'
 require_relative '../lib/gitlab_quality/test_tooling/code_coverage/coverage_data'
 require_relative '../lib/gitlab_quality/test_tooling/code_coverage/lcov_file'
 require_relative '../lib/gitlab_quality/test_tooling/code_coverage/artifacts'
 require_relative '../lib/gitlab_quality/test_tooling/code_coverage/test_report'
 require_relative '../lib/gitlab_quality/test_tooling/code_coverage/test_map'
+require_relative '../lib/gitlab_quality/test_tooling/code_coverage/test_file_mapping_data'
 require_relative '../lib/gitlab_quality/test_tooling/code_coverage/source_file_classifier'
+require_relative '../lib/gitlab_quality/test_tooling/code_coverage/responsibility_classifier'
+require_relative '../lib/gitlab_quality/test_tooling/code_coverage/responsibility_patterns_config'
 
 params = {}
-required_params = [:test_reports, :coverage_report, :test_map, :clickhouse_url, :clickhouse_database, :clickhouse_username]
+required_params = [:test_reports, :coverage_report, :test_map, :clickhouse_url, :clickhouse_database, :clickhouse_username, :responsibility_patterns]
 
 options = OptionParser.new do |opts|
   opts.banner = "Usage: #{$PROGRAM_NAME} [options]"
@@ -50,6 +55,10 @@ options = OptionParser.new do |opts|
     params[:clickhouse_username] = username
   end
 
+  opts.on('--responsibility-patterns PATH', 'Path to YAML file with responsibility classification patterns') do |path|
+    params[:responsibility_patterns] = path
+  end
+
   opts.separator ""
   opts.separator "Environment variables:"
   opts.separator "  GLCI_CLICKHOUSE_METRICS_PASSWORD   ClickHouse password (required, not passed via CLI for security)"
@@ -107,7 +116,9 @@ if params.any? && (required_params - params.keys).none?
 
   code_coverage_by_source_file = GitlabQuality::TestTooling::CodeCoverage::LcovFile.new(coverage_report).parsed_content
 
-  source_file_to_tests = GitlabQuality::TestTooling::CodeCoverage::TestMap.new(test_map).source_to_tests
+  test_map_parser = GitlabQuality::TestTooling::CodeCoverage::TestMap.new(test_map)
+  source_file_to_tests = test_map_parser.source_to_tests
+  test_to_sources = test_map_parser.test_to_sources
 
   # Process test reports
   tests_to_categories = artifacts.test_reports.reduce({}) do |combined_hash, test_report_file|
@@ -121,12 +132,31 @@ if params.any? && (required_params - params.keys).none?
   source_file_classifier = GitlabQuality::TestTooling::CodeCoverage::SourceFileClassifier.new
   source_file_types = source_file_classifier.classify(code_coverage_by_source_file.keys)
 
+  # Load responsibility patterns from config file
+  begin
+    patterns_config = GitlabQuality::TestTooling::CodeCoverage::ResponsibilityPatternsConfig.new(
+      params[:responsibility_patterns]
+    )
+  rescue GitlabQuality::TestTooling::CodeCoverage::ResponsibilityPatternsConfig::ConfigError => e
+    puts "Error: #{e.message}"
+    exit 1
+  end
+
+  # Classify test files as responsible or dependent
+  responsibility_classifier = GitlabQuality::TestTooling::CodeCoverage::ResponsibilityClassifier.new(
+    test_to_sources,
+    responsible_patterns: patterns_config.responsible_patterns,
+    dependent_patterns: patterns_config.dependent_patterns
+  )
+  test_classifications = responsibility_classifier.classify_tests
+
   coverage_data = GitlabQuality::TestTooling::CodeCoverage::CoverageData.new(
     code_coverage_by_source_file,
     source_file_to_tests,
     tests_to_categories,
-    category_owners.categories_to_teams,
-    source_file_types
+    category_owners.feature_categories_to_teams,
+    source_file_types,
+    test_classifications
   )
 
   clickhouse_data = {
@@ -139,15 +169,17 @@ if params.any? && (required_params - params.keys).none?
   category_owners_table  = GitlabQuality::TestTooling::CodeCoverage::ClickHouse::CategoryOwnersTable.new(**clickhouse_data)
   coverage_metrics_table = GitlabQuality::TestTooling::CodeCoverage::ClickHouse::CoverageMetricsTable.new(**clickhouse_data)
 
-  category_owners_table.create  if ENV['CLICKHOUSE_CREATE_CATEGORY_OWNERS_TABLE']  == 'true'
-  coverage_metrics_table.create if ENV['CLICKHOUSE_CREATE_COVERAGE_METRICS_TABLE'] == 'true'
-
   if ENV['CLICKHOUSE_PUSH_CATEGORY_DATA'] == 'true'
     category_owners_table.truncate
     category_owners_table.push(category_owners.as_db_table)
   end
 
   coverage_metrics_table.push(coverage_data.as_db_table)
+
+  # Export test-to-file mappings
+  test_file_mapping_data = GitlabQuality::TestTooling::CodeCoverage::TestFileMappingData.new(test_to_sources)
+  test_file_mappings_table = GitlabQuality::TestTooling::CodeCoverage::ClickHouse::TestFileMappingsTable.new(**clickhouse_data)
+  test_file_mappings_table.push(test_file_mapping_data.as_db_table)
 else
   puts "Missing argument(s). Required arguments are: #{required_params}\nPassed arguments are: #{params}\n"
   puts options

data/lib/gitlab_quality/test_tooling/code_coverage/README.md

@@ -0,0 +1,162 @@
+# Code Coverage Module
+
+Exports test coverage data to ClickHouse, enriched with:
+
+- **Feature category ownership** - group, stage, and section for each covered file
+- **Responsibility classification** - whether coverage comes from unit or integration tests
+- **Test-to-file mappings** - which source files each test covers
+
+## How It Works
+
+### Feature Category Attribution
+
+Coverage data is enriched with feature category ownership by joining three data sources:
+
+1. **Coverage Report** (LCOV) - which source files have coverage and their percentages
+2. **Test Map** - which test files cover each source file
+3. **Test Reports** (JSON) - which feature category each test file belongs to
+
+```mermaid
+flowchart LR
+    subgraph Inputs
+        A["<b>Coverage Report</b><br/>user.rb: 85%"]
+        B["<b>Test Map</b><br/>user.rb → user_spec.rb"]
+        C["<b>Test Reports</b><br/>user_spec.rb → user_profile"]
+    end
+
+    subgraph Output
+        E["<b>ClickHouse Record</b><br/>file: user.rb<br/>feature_category: user_profile<br/>coverage: 85%"]
+    end
+
+    A --> D((Join))
+    B --> D
+    C --> D
+    D --> E
+```
+
+This enables **multi-category attribution**: if a source file is covered by tests from
+multiple feature categories, it creates a separate record for each category in ClickHouse.
+
+### Why All Three Inputs Are Required
+
+| Input | Provides | Without it |
+|-------|----------|------------|
+| Coverage Report | Line/branch coverage percentages | No coverage metrics |
+| Test Map | Source file → test file relationships | No feature category attribution (all records have `category=NULL`) |
+| Test Reports | Test file → feature category metadata | No feature category attribution (all records have `category=NULL`) |
+
+## Responsibility Classification
+
+Tests are classified as either **responsible** or **dependent**:
+
+- **Responsible**: Unit tests that directly test a component in isolation
+- **Dependent**: Integration/E2E tests that exercise a component through other layers
+
+This classification is tracked per (source_file, feature_category) combination using two boolean columns:
+
+| is_responsible | is_dependent | Meaning |
+|----------------|--------------|---------|
+| `true` | `true` | Source file has both unit AND integration test coverage from this feature category |
+| `true` | `false` | Source file has only unit test coverage from this feature category |
+| `false` | `true` | Source file has only integration test coverage from this feature category |
+| `nil` | `nil` | No test mapping exists for this source file |
+
+### Configuration
+
+This gem is designed to be reusable across different projects. Classification patterns
+are project-specific and must be provided via a YAML config file, since different
+codebases have different test directory structures. The config file defines regex
+patterns for matching test file paths:
+
+> **Note:** The table above describes the *semantic meaning* of the flags. The patterns
+> you configure determine *which tests* produce those flags for your project.
+
+```yaml
+# responsibility_patterns.yml
+responsible:
+  - "^spec/(models|controllers|services)/"   # Backend unit tests
+  - "^spec/frontend/"                        # Frontend unit tests
+  - "_test\\.go$"                            # Go unit tests
+
+dependent:
+  - "^spec/(requests|features|integration)/" # Backend integration tests
+  - "^spec/frontend_integration/"            # Frontend integration tests
+  - "^qa/"                                   # E2E tests
+  - "_integration_test\\.go$"                # Go integration tests
+```
+
+**Pattern matching rules:**
+1. Dependent patterns are checked first (higher priority)
+2. If no pattern matches, the test defaults to "dependent"
+3. Patterns are Ruby regexes (escape special characters like `.` with `\\`)
+
+**Why dependent has priority:** We use a conservative approach. `is_responsible: true`
+makes a stronger claim ("this file has unit test coverage") than `is_dependent: true`.
+If a test matches both patterns or no patterns, defaulting to "dependent" avoids
+incorrectly inflating unit test coverage metrics. It's safer to under-claim than over-claim.
+
+### Example: GitLab Configuration
+
+```yaml
+# .gitlab/coverage/responsibility_patterns.yml
+responsible:
+  # Backend unit test directories
+  - "^spec/(models|controllers|services|workers|helpers|mailers|policies|presenters|uploaders|validators|lib|graphql|serializers|components)/"
+  - "^ee/spec/(models|controllers|services|workers|helpers|mailers|policies|presenters|uploaders|validators|lib|graphql|serializers|components)/"
+  # Frontend unit tests
+  - "^spec/frontend/"
+  - "^ee/spec/frontend/"
+  # Go unit tests
+  - "_test\\.go$"
+
+dependent:
+  # Backend integration tests
+  - "^spec/(requests|features|system|integration)/"
+  - "^ee/spec/(requests|features|system|integration)/"
+  # Frontend integration tests
+  - "^spec/frontend_integration/"
+  - "^ee/spec/frontend_integration/"
+  # E2E tests
+  - "^qa/"
+  # Go integration tests
+  - "_integration_test\\.go$"
+```
+
+### Example: Standard Rails Project
+
+```yaml
+# config/responsibility_patterns.yml
+responsible:
+  - "^test/(models|controllers|services|helpers|mailers)/"
+  - "^test/unit/"
+
+dependent:
+  - "^test/(integration|system)/"
+  - "^spec/features/"
+```
+
+## Test-to-File Mappings
+
+When a test map is provided, the module also exports test-to-source-file relationships
+to a separate `test_file_mappings` table. This enables:
+
+- **Coverage context for tests** - see which source files a specific test covers
+- **Impact analysis** - understand which files would lose coverage if a test is quarantined
+- **Flaky test triage** - correlate flaky tests with the source files they cover
+
+## CLI
+
+Example usage:
+
+```bash
+test-coverage \
+  --test-reports 'rspec/*.json' \
+  --coverage-report 'coverage/lcov.info' \
+  --test-map 'mapping.json' \
+  --responsibility-patterns 'config/responsibility_patterns.yml' \
+  --clickhouse-url 'https://clickhouse.example.com' \
+  --clickhouse-database 'coverage' \
+  --clickhouse-username 'user'
+```
+
+See `exe/test-coverage --help` for full usage.

data/lib/gitlab_quality/test_tooling/code_coverage/artifacts.rb

@@ -11,7 +11,8 @@ module GitlabQuality
       class Artifacts
         # Loads coverage artifacts from the filesystem
         #
-        # @param test_reports [String] Glob pattern for test JSON report files (RSpec or Jest) (e.g., "reports/**/*.json")
+        # @param test_reports [String] Glob pattern(s) for test JSON report files (RSpec or Jest).
+        #   Supports comma-separated patterns (e.g., "jest/**/*.json,rspec/**/*.json")
         # @param coverage_report [String] Path to the LCOV coverage report file (e.g., "coverage/lcov/gitlab.lcov")
         # @param test_map [String] Path to the test map file, gzipped or plain JSON (e.g., "crystalball/packed-mapping.json.gz")
         def initialize(coverage_report:, test_map:, test_reports:)
@@ -54,7 +55,9 @@ module GitlabQuality
 
         def test_reports_paths
           @test_reports_paths ||= begin
-            paths = Dir.glob(@test_reports_glob)
+            # Support comma-separated glob patterns (e.g., "jest/**/*.json,rspec/**/*.json")
+            patterns = @test_reports_glob.split(',').map(&:strip).reject(&:empty?)
+            paths = Dir.glob(patterns)
 
             raise "No test reports found matching pattern: #{@test_reports_glob}" if paths.empty?
 

data/lib/gitlab_quality/test_tooling/code_coverage/category_owners.rb

@@ -15,17 +15,17 @@ module GitlabQuality
         BASE_DELAY  = 1 # seconds
         MAX_RETRIES = 3
 
-        # @return [Hash] Category ownership hierarchy, section -> stage -> group -> [categories]
+        # @return [Hash] Feature category ownership hierarchy, section -> stage -> group -> [feature_categories]
         # @example Return value
         #   {
         #     "team_planning" => {             # section
         #       "project_management" => {      # stage
         #         "plan" => [                  # group
-        #           "dev",                     # category
-        #           "service_desk"             # category
+        #           "dev",                     # feature_category
+        #           "service_desk"             # feature_category
         #         ],
         #         "product_planning" => [      # group
-        #           "portfolio_management",    # category
+        #           "portfolio_management",    # feature_category
         #           ...
         #         ]
         #       }
@@ -35,7 +35,7 @@ module GitlabQuality
         attr_reader :hierarchy
 
         def initialize
-          @categories_map = {}
+          @feature_categories_map = {}
           @hierarchy = {}
 
           yaml_file = fetch_yaml_file
@@ -43,12 +43,12 @@ module GitlabQuality
           populate_ownership_hierarchy(yaml_content)
         end
 
-        # @return [Array<Hash>] Flattened category ownership
+        # @return [Array<Hash>] Flattened feature category ownership
         # @example Return value
         #   [
-        #     { category: "team_planning", group: "project_management", stage: "plan", section: "dev" },
-        #     { category: "service_desk", group: "project_management", stage: "plan", section: "dev" },
-        #     { category: "portfolio_management", group: "product_planning", stage: "plan", section: "dev" }
+        #     { feature_category: "team_planning", group: "project_management", stage: "plan", section: "dev" },
+        #     { feature_category: "service_desk", group: "project_management", stage: "plan", section: "dev" },
+        #     { feature_category: "portfolio_management", group: "product_planning", stage: "plan", section: "dev" }
         #     ...
         #   ]
         def as_db_table
@@ -58,10 +58,10 @@ module GitlabQuality
             stages.each do |stage, groups|
               next unless groups
 
-              groups.each do |group, categories|
-                Array(categories).each do |category|
+              groups.each do |group, feature_categories|
+                Array(feature_categories).each do |feature_category|
                   flattened_hierarchy << {
-                    category: category,
+                    feature_category: feature_category,
                     group: group,
                     stage: stage,
                     section: section
@@ -72,7 +72,7 @@ module GitlabQuality
           end
         end
 
-        # @return [Hash] Mapping of categories to teams (i.e., groups, stages, sections)
+        # @return [Hash] Mapping of feature categories to teams (i.e., groups, stages, sections)
         # @example Return value
         #   {
         #     "team_planning" => { group: "project_management", stage: "plan", section: "dev" },
@@ -80,9 +80,9 @@ module GitlabQuality
         #     "portfolio_management" => { group: "product_planning", stage: "plan", section: "dev" },
         #     ...
         #   }
-        def categories_to_teams
-          populate_categories_map(hierarchy)
-          @categories_map
+        def feature_categories_to_teams
+          populate_feature_categories_map(hierarchy)
+          @feature_categories_map
         end
 
         private
@@ -126,25 +126,25 @@ module GitlabQuality
           @hierarchy[section][stage][group] = categories || []
         end
 
-        def populate_categories_map(data, current_section = nil, current_stage = nil, current_group = nil)
+        def populate_feature_categories_map(data, current_section = nil, current_stage = nil, current_group = nil)
           case data
           when Hash # Sections / Stages / Groups
             data.each do |key, value|
               if current_section.nil? # Sections
-                populate_categories_map(value, key, nil, nil)
+                populate_feature_categories_map(value, key, nil, nil)
               elsif current_stage.nil? # Stages
-                populate_categories_map(value, current_section, key, nil)
+                populate_feature_categories_map(value, current_section, key, nil)
               elsif current_group.nil? # Groups
-                populate_categories_map(value, current_section, current_stage, key)
-              else                     # Categories
-                populate_categories_map(value, current_section, current_stage, current_group)
+                populate_feature_categories_map(value, current_section, current_stage, key)
+              else                     # Feature categories
+                populate_feature_categories_map(value, current_section, current_stage, current_group)
               end
             end
-          when Array # Categories array
-            data.each do |category|
-              next unless category.is_a?(String)
+          when Array # Feature categories array
+            data.each do |feature_category|
+              next unless feature_category.is_a?(String)
 
-              @categories_map[category] = {
+              @feature_categories_map[feature_category] = {
                 section: current_section,
                 stage: current_stage,
                 group: current_group

data/lib/gitlab_quality/test_tooling/code_coverage/click_house/category_owners_table.rb

@@ -11,29 +11,6 @@ module GitlabQuality
 
           MissingMappingError = Class.new(StandardError)
 
-          # Creates the ClickHouse table, if it doesn't exist already
-          # @return [nil]
-          def create
-            logger.debug("#{LOG_PREFIX} Creating category_owners table if it doesn't exist ...")
-
-            client.query(<<~SQL)
-              CREATE TABLE IF NOT EXISTS #{table_name} (
-                timestamp DateTime64(6, 'UTC') DEFAULT now64(),
-                category String,
-                group String,
-                stage String,
-                section String,
-                INDEX idx_group group TYPE set(360) GRANULARITY 1,
-                INDEX idx_stage stage TYPE set(360) GRANULARITY 1,
-                INDEX idx_section section TYPE set(360) GRANULARITY 1
-              ) ENGINE = MergeTree()
-              ORDER BY (category, timestamp)
-              SETTINGS index_granularity = 8192;
-            SQL
-
-            logger.info("#{LOG_PREFIX} Category owners table created/verified successfully")
-          end
-
           def truncate
             logger.debug("#{LOG_PREFIX} Truncating table #{full_table_name} ...")
 
@@ -42,14 +19,14 @@ module GitlabQuality
             logger.info("#{LOG_PREFIX} Successfully truncated table #{full_table_name}")
           end
 
-          # Owners of particular category as group, stage and section
+          # Owners of particular feature category as group, stage and section
           #
-          # @param category_name [String]
+          # @param feature_category_name [String] the feature_category name
           # @return [Hash]
-          def owners(category_name)
-            records.fetch(category_name)
+          def owners(feature_category_name)
+            records.fetch(feature_category_name)
           rescue KeyError
-            raise(MissingMappingError, "Category '#{category_name}' not found in table '#{table_name}'")
+            raise(MissingMappingError, "Feature category '#{feature_category_name}' not found in table '#{table_name}'")
           end
 
           private

data/lib/gitlab_quality/test_tooling/code_coverage/click_house/coverage_metrics_table.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'time'
 require_relative 'table'
 
 module GitlabQuality
@@ -10,37 +9,6 @@ module GitlabQuality
         class CoverageMetricsTable < GitlabQuality::TestTooling::CodeCoverage::ClickHouse::Table
           TABLE_NAME = "coverage_metrics"
 
-          # Creates the ClickHouse table, if it doesn't exist already
-          # @return [nil]
-          def create
-            logger.debug("#{LOG_PREFIX} Creating coverage_metrics table if it doesn't exist ...")
-
-            client.query(<<~SQL)
-              CREATE TABLE IF NOT EXISTS #{table_name} (
-                timestamp DateTime64(6, 'UTC'),
-                file String,
-                line_coverage Float64,
-                branch_coverage Nullable(Float64),
-                function_coverage Nullable(Float64),
-                source_file_type String,
-                category Nullable(String),
-                ci_project_id Nullable(UInt32),
-                ci_project_path Nullable(String),
-                ci_job_name Nullable(String),
-                ci_job_id Nullable(UInt64),
-                ci_pipeline_id Nullable(UInt64),
-                ci_merge_request_iid Nullable(UInt32),
-                ci_branch Nullable(String),
-                ci_target_branch Nullable(String)
-              ) ENGINE = MergeTree()
-              PARTITION BY toYYYYMM(timestamp)
-              ORDER BY (ci_project_path, timestamp, file, ci_pipeline_id)
-              SETTINGS index_granularity = 8192, allow_nullable_key = 1;
-            SQL
-
-            logger.info("#{LOG_PREFIX} Coverage metrics table created/verified successfully")
-          end
-
           private
 
           # @return [Boolean] True if the record is valid, false otherwise
@@ -97,19 +65,13 @@ module GitlabQuality
               branch_coverage: record[:branch_coverage],
               function_coverage: record[:function_coverage],
               source_file_type: record[:source_file_type],
-              category: record[:category],
+              is_responsible: record[:is_responsible],
+              is_dependent: record[:is_dependent],
+              category: record[:feature_category],
               **ci_metadata
             }
           end
 
-          # @return [Time] Common timestamp for all coverage records
-          def time
-            @time ||= begin
-              ci_created_at = ENV.fetch('CI_PIPELINE_CREATED_AT', nil)
-              ci_created_at ? Time.strptime(ci_created_at, '%Y-%m-%dT%H:%M:%S%z') : Time.now.utc
-            end
-          end
-
           # @return [Hash] CI-related metadata
           def ci_metadata
             {

data/lib/gitlab_quality/test_tooling/code_coverage/click_house/table.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'time'
+
 module GitlabQuality
   module TestTooling
     module CodeCoverage
@@ -58,6 +60,21 @@ module GitlabQuality
             raise NotImplementedError, "#{self.class}##{__method__} method must be implemented in a subclass"
           end
 
+          # @return [Time] Common timestamp for all records, memoized
+          def time
+            @time ||= parse_ci_timestamp
+          end
+
+          def parse_ci_timestamp
+            ci_created_at = ENV.fetch('CI_PIPELINE_CREATED_AT', nil)
+            return Time.now.utc unless ci_created_at
+
+            Time.strptime(ci_created_at, '%Y-%m-%dT%H:%M:%S%z')
+          rescue ArgumentError
+            logger.warn("#{LOG_PREFIX} Invalid CI_PIPELINE_CREATED_AT format: #{ci_created_at}, using current time")
+            Time.now.utc
+          end
+
           # @return [GitlabQuality::TestTooling::ClickHouse::Client]
           def client
             @client ||= GitlabQuality::TestTooling::ClickHouse::Client.new(

data/lib/gitlab_quality/test_tooling/code_coverage/click_house/test_file_mappings_table.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'table'
+
+module GitlabQuality
+  module TestTooling
+    module CodeCoverage
+      module ClickHouse
+        class TestFileMappingsTable < GitlabQuality::TestTooling::CodeCoverage::ClickHouse::Table
+          TABLE_NAME = "test_file_mappings"
+
+          private
+
+          # @return [Boolean] True if the record is valid, false otherwise
+          def valid_record?(record)
+            valid_test_file?(record) && valid_source_file?(record)
+          end
+
+          # @return [Boolean] True if the test_file field is present
+          def valid_test_file?(record)
+            return true unless record[:test_file].blank?
+
+            logger.warn("#{LOG_PREFIX} Skipping record with nil/empty test_file: #{record}")
+            false
+          end
+
+          # @return [Boolean] True if the source_file field is present
+          def valid_source_file?(record)
+            return true unless record[:source_file].blank?
+
+            logger.warn("#{LOG_PREFIX} Skipping record with nil/empty source_file: #{record}")
+            false
+          end
+
+          # @return [Hash] Transformed mapping data including timestamp and CI metadata
+          def sanitized_data_record(record)
+            {
+              timestamp: time,
+              test_file: record[:test_file],
+              source_file: record[:source_file],
+              ci_project_path: ENV.fetch('CI_PROJECT_PATH', nil)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab_quality/test_tooling/code_coverage/coverage_data.rb

@@ -4,22 +4,31 @@ module GitlabQuality
   module TestTooling
     module CodeCoverage
       class CoverageData
+        RESPONSIBLE = 'responsible'
+        DEPENDENT = 'dependent'
+
         # @param [Hash<String, Hash>] code_coverage_by_source_file Source file
         #   mapped to test coverage data
         # @param [Hash<String, Array<String>>] source_file_to_tests Source files
         #   mapped to all test files testing them
-        # @param [Hash<String, Array<String>>] tests_to_categories Test files
+        # @param [Hash<String, Array<String>>] tests_to_feature_categories Test files
         #   mapped to all feature categories they belong to
-        # @param [Hash<String, Hash>] categories_to_teams Mapping of categories
+        # @param [Hash<String, Hash>] feature_categories_to_teams Mapping of feature categories
         #   to teams (i.e., groups, stages, sections)
         # @param [Hash<String, String>] source_file_types Mapping of source files
         #   to their types (frontend, backend, etc.)
-        def initialize(code_coverage_by_source_file, source_file_to_tests, tests_to_categories, categories_to_teams, source_file_types = {})
+        # @param [Hash<String, String>] test_classifications Mapping of test files
+        #   to their responsibility classification (responsible or dependent)
+        def initialize(
+          code_coverage_by_source_file, source_file_to_tests, tests_to_feature_categories,
+          feature_categories_to_teams, source_file_types = {}, test_classifications = {}
+        )
           @code_coverage_by_source_file = code_coverage_by_source_file
           @source_file_to_tests = source_file_to_tests
-          @tests_to_categories = tests_to_categories
-          @categories_to_teams = categories_to_teams
+          @tests_to_feature_categories = tests_to_feature_categories
+          @feature_categories_to_teams = feature_categories_to_teams
           @source_file_types = source_file_types
+          @test_classifications = test_classifications
         end
 
         # @return [Array<Hash<Symbol, String>>] Mapping of column name to row
@@ -32,7 +41,9 @@ module GitlabQuality
         #       branch_coverage: 95.0
         #       function_coverage: 100.0
         #       source_file_type: "backend"
-        #       category: "team_planning"
+        #       is_responsible: true
+        #       is_dependent: false
+        #       feature_category: "team_planning"
         #       group: "project_management"
         #       stage: "plan"
         #       section: "dev"
@@ -40,55 +51,81 @@ module GitlabQuality
         #     ...
         #   ]
         def as_db_table
-          all_files.flat_map do |file|
-            coverage_data = @code_coverage_by_source_file[file]
-            line_coverage = coverage_data&.dig(:percentage)
-            branch_coverage = coverage_data&.dig(:branch_percentage)
-            function_coverage = coverage_data&.dig(:function_percentage)
-
-            categories = categories_for(file)
-            base_data = {
-              file: file,
-              line_coverage: line_coverage,
-              branch_coverage: branch_coverage,
-              function_coverage: function_coverage,
-              source_file_type: @source_file_types[file] || 'other'
-            }
-
-            if categories.empty?
-              base_data.merge(no_owner_info)
-            else
-              categories.map do |category|
-                base_data.merge(owner_info(category))
-              end
+          all_files.flat_map { |file| records_for_file(file) }
+        end
+
+        private
+
+        def records_for_file(file)
+          base_data = base_data_for(file)
+          feature_categories_with_flags = feature_categories_with_responsibility_flags_for(file)
+
+          if feature_categories_with_flags.empty?
+            base_data.merge(no_owner_info).merge(is_responsible: nil, is_dependent: nil)
+          else
+            feature_categories_with_flags.map do |feature_category, flags|
+              base_data.merge(owner_info(feature_category)).merge(
+                is_responsible: flags[:is_responsible],
+                is_dependent: flags[:is_dependent]
+              )
             end
           end
         end
 
-        private
+        def base_data_for(file)
+          coverage_data = @code_coverage_by_source_file[file]
+
+          {
+            file: file,
+            line_coverage: coverage_data&.dig(:percentage),
+            branch_coverage: coverage_data&.dig(:branch_percentage),
+            function_coverage: coverage_data&.dig(:function_percentage),
+            source_file_type: @source_file_types[file] || 'other'
+          }
+        end
 
         def no_owner_info
           {
-            category: nil,
+            feature_category: nil,
             group: nil,
             stage: nil,
             section: nil
           }
         end
 
-        def owner_info(category)
-          owner_info = @categories_to_teams[category]
+        def owner_info(feature_category)
+          owner_info = @feature_categories_to_teams[feature_category]
 
           {
-            category: category,
+            feature_category: feature_category,
             group: owner_info&.dig(:group),
             stage: owner_info&.dig(:stage),
             section: owner_info&.dig(:section)
           }
         end
 
-        def categories_for(file)
-          @source_file_to_tests[file]&.flat_map { |test_file| @tests_to_categories[test_file] || [] }&.uniq || []
+        # Returns a hash of feature_category => { is_responsible: bool, is_dependent: bool }
+        # for a given source file. A feature category can have both flags true if it has
+        # both unit tests (responsible) and integration/E2E tests (dependent).
+        def feature_categories_with_responsibility_flags_for(file)
+          test_files = @source_file_to_tests[file] || []
+          return {} if test_files.empty?
+
+          test_files.each_with_object({}) do |test_file, feature_category_to_flags|
+            feature_categories = @tests_to_feature_categories[test_file] || []
+            classification = @test_classifications[test_file]
+
+            feature_categories.each do |feature_category|
+              feature_category_to_flags[feature_category] ||= { is_responsible: false, is_dependent: false }
+
+              case classification
+              when RESPONSIBLE
+                feature_category_to_flags[feature_category][:is_responsible] = true
+              when DEPENDENT
+                feature_category_to_flags[feature_category][:is_dependent] = true
+              end
+            end
+          end
         end
 
         def all_files

data/lib/gitlab_quality/test_tooling/code_coverage/lcov_file.rb

@@ -85,7 +85,7 @@ module GitlabQuality
         end
 
         def register_source_file(filename)
-          @current_file = filename.gsub(%r{^\./}, '')
+          @current_file = normalize_path(filename)
           @parsed_content[@current_file] = {
             line_coverage: {},
             branch_coverage: {},
@@ -94,6 +94,16 @@ module GitlabQuality
           }
         end
 
+        def normalize_path(filename)
+          # Remove leading ./ if present
+          path = filename.gsub(%r{^\./}, '')
+
+          # Handle GDK/CI paths like "../../../home/gdk/gitlab-development-kit/gitlab/app/..."
+          # Extract path starting from known root directories
+          match = path.match(%r{((?:ee/)?(?:app|lib|config|db|spec|scripts|tooling|workhorse|vendor)/.+)$})
+          match ? match[1] : path
+        end
+
         def register_line_data(line_no, count)
           return unless @current_file
 

data/lib/gitlab_quality/test_tooling/code_coverage/responsibility_classifier.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module GitlabQuality
+  module TestTooling
+    module CodeCoverage
+      class ResponsibilityClassifier
+        RESPONSIBLE = 'responsible'
+        DEPENDENT = 'dependent'
+
+        # @param test_to_sources [Hash<String, Array<String>>] Test files mapped to source files they cover
+        # @param responsible_patterns [Array<Regexp>] Patterns for unit tests
+        # @param dependent_patterns [Array<Regexp>] Patterns for integration/E2E tests
+        def initialize(test_to_sources, responsible_patterns:, dependent_patterns:)
+          @test_to_sources = test_to_sources
+          @responsible_patterns = responsible_patterns
+          @dependent_patterns = dependent_patterns
+        end
+
+        # Classifies each test file as responsible or dependent
+        # @return [Hash<String, String>] Test file path => classification
+        def classify_tests
+          @test_to_sources.keys.each_with_object({}) do |test_file, result|
+            result[test_file] = classify_test(test_file)
+          end
+        end
+
+        private
+
+        # Classifies a test file as responsible (unit) or dependent (integration/E2E).
+        #
+        # Dependent patterns are checked first because it's the safer default:
+        # - is_responsible: true claims "this file has unit test coverage"
+        # - is_dependent: true claims "this file has integration test coverage"
+        #
+        # If uncertain (overlapping patterns or no match), we default to dependent
+        # to avoid incorrectly inflating unit test coverage metrics.
+        def classify_test(test_file)
+          return DEPENDENT if @dependent_patterns.any? { |p| test_file.match?(p) }
+          return RESPONSIBLE if @responsible_patterns.any? { |p| test_file.match?(p) }
+
+          # Default to dependent for unknown test types
+          DEPENDENT
+        end
+      end
+    end
+  end
+end

data/lib/gitlab_quality/test_tooling/code_coverage/responsibility_patterns_config.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module GitlabQuality
+  module TestTooling
+    module CodeCoverage
+      class ResponsibilityPatternsConfig
+        ConfigError = Class.new(StandardError)
+
+        attr_reader :responsible_patterns, :dependent_patterns
+
+        # @param file_path [String] Path to YAML config file
+        # @raise [ConfigError] if file cannot be loaded or parsed
+        def initialize(file_path)
+          @file_path = file_path
+          @config = load_config
+          @responsible_patterns = parse_patterns('responsible')
+          @dependent_patterns = parse_patterns('dependent')
+        end
+
+        private
+
+        def load_config
+          YAML.load_file(@file_path)
+        rescue Errno::ENOENT
+          raise ConfigError, "Config file not found: #{@file_path}"
+        rescue Psych::SyntaxError => e
+          raise ConfigError, "Invalid YAML syntax in #{@file_path}: #{e.message}"
+        end
+
+        def parse_patterns(key)
+          patterns = @config[key]
+
+          raise ConfigError, "Missing or invalid '#{key}' key in #{@file_path}. Expected an array of patterns." unless patterns.is_a?(Array)
+
+          patterns.map do |pattern|
+            Regexp.new(pattern)
+          rescue RegexpError => e
+            raise ConfigError, "Invalid regex pattern '#{pattern}' in #{@file_path}: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab_quality/test_tooling/code_coverage/test_file_mapping_data.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module GitlabQuality
+  module TestTooling
+    module CodeCoverage
+      class TestFileMappingData
+        # @param [Hash<String, Array<String>>] test_to_sources Test files
+        #   mapped to all source files they cover
+        def initialize(test_to_sources)
+          @test_to_sources = test_to_sources
+        end
+
+        # @return [Array<Hash<Symbol, String>>] Mapping data formatted for database insertion
+        # @example Return value
+        #   [
+        #     { test_file: "spec/models/user_spec.rb", source_file: "app/models/user.rb" },
+        #     { test_file: "spec/models/user_spec.rb", source_file: "lib/utils.rb" },
+        #     ...
+        #   ]
+        def as_db_table
+          @test_to_sources.flat_map do |test_file, source_files|
+            source_files.map do |source_file|
+              {
+                test_file: test_file,
+                source_file: source_file
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab_quality/test_tooling/test_metrics_exporter/config.rb

@@ -52,6 +52,7 @@ module GitlabQuality
           :skip_record_proc,
           :test_retried_proc,
           :custom_metrics_proc,
+          :spec_file_path_prefix,
           :logger
 
         # rubocop:disable Style/TrivialAccessors -- allows documenting that setting config enables the export as well as document input class type
@@ -108,6 +109,13 @@ module GitlabQuality
           @extra_rspec_metadata_keys ||= []
         end
 
+        # Extra path prefix for constructing full file path within mono-repository setups
+        #
+        # @return [String]
+        def spec_file_path_prefix
+          @spec_file_path_prefix ||= ""
+        end
+
         # A lambda that determines whether to skip recording a test result
         #
         # This is useful when you would want to skip initial failure when retrying specs is set up in a separate process

data/lib/gitlab_quality/test_tooling/test_metrics_exporter/test_metrics.rb

@@ -46,12 +46,15 @@ module GitlabQuality
             status: example.execution_result.status,
             run_time: (example.execution_result.run_time * 1000).round,
             location: example_location,
-            exception_class: exception_class,
+            # TODO: remove exception_class once migration to exception_classes is fully complete on clickhouse side
+            exception_class: example.execution_result.exception&.class&.to_s,
+            exception_classes: exception_classes.map { |e| e.class.to_s }.uniq,
             failure_exception: failure_exception,
             quarantined: quarantined?,
             feature_category: example.metadata[:feature_category] || "",
             test_retried: config.test_retried_proc.call(example),
-            run_type: run_type
+            run_type: run_type,
+            spec_file_path_prefix: config.spec_file_path_prefix
           }
         end
 
@@ -127,22 +130,25 @@ module GitlabQuality
           @file_path ||= example_location.gsub(/:\d+$/, "")
         end
 
-        # Failure exception class
+        # Failure exception classes
         #
-        # @return [String]
-        def exception_class
-          example.execution_result.exception&.class&.to_s
+        # @return [Array<Exception>]
+        def exception_classes
+          exception = example.execution_result.exception
+          return [] unless exception
+          return [exception] unless exception.respond_to?(:all_exceptions)
+
+          exception.all_exceptions.flatten
         end
 
         # Truncated exception stacktrace
         #
         # @return [String]
         def failure_exception
-          example.execution_result.exception.then do |exception|
-            next unless exception
+          exception = example.execution_result.exception
+          return unless exception
 
-            exception.to_s.tr("\n", " ").slice(0, 1000)
-          end
+          exception.to_s.tr("\n", " ").slice(0, 1000)
         end
 
         # Test run type | suite name

data/lib/gitlab_quality/test_tooling/test_metrics_exporter/utils.rb

@@ -65,6 +65,7 @@ module GitlabQuality
                 test_retried Bool,
                 feature_category LowCardinality(String) DEFAULT 'unknown',
                 run_type LowCardinality(String) DEFAULT 'unknown',
+                spec_file_path_prefix LowCardinality(String) DEFAULT '',
                 ci_project_id UInt32,
                 ci_job_name LowCardinality(String),
                 ci_job_id UInt64,
@@ -75,6 +76,7 @@ module GitlabQuality
                 ci_target_branch LowCardinality(String),
                 ci_server_url LowCardinality(String) DEFAULT 'https://gitlab.com',
                 exception_class String DEFAULT '',
+                exception_classes Array(String) DEFAULT [],
                 failure_exception String DEFAULT ''
             )
             ENGINE = MergeTree()

data/lib/gitlab_quality/test_tooling/test_result/base_test_result.rb

@@ -8,6 +8,7 @@ module GitlabQuality
           "Net::ReadTimeout",
           "403 Forbidden - Your account has been blocked",
           "API failed (502) with `GitLab is not responding",
+          "Error Code: 502",
           "unexpected token at 'GitLab is not responding'",
           "GitLab: Internal API error (502).",
           "could not be found (502)",
@@ -127,14 +128,26 @@ module GitlabQuality
         end
 
         def full_stacktrace
+          page_error_failure = ""
+          first_non_ignored_failure = ""
+
           failures.each do |failure|
             message = failure['message'] || ""
             message_lines = failure['message_lines'] || []
 
             next if IGNORED_FAILURES.any? { |e| message.include?(e) }
 
-            return message_lines.empty? ? message : message_lines.join("\n")
+            formatted_failure = message_lines.empty? ? message : message_lines.join("\n")
+
+            if message.include?("PageErrorChecker")
+              page_error_failure = formatted_failure
+            elsif first_non_ignored_failure.empty?
+              first_non_ignored_failure = formatted_failure
+            end
           end
+
+          # Return PageErrorChecker failure if found, otherwise first non-ignored failure
+          page_error_failure.empty? ? first_non_ignored_failure : page_error_failure
         end
 
         def calls_shared_examples?

data/lib/gitlab_quality/test_tooling/version.rb

@@ -2,6 +2,6 @@
 
 module GitlabQuality
   module TestTooling
-    VERSION = "3.0.0"
+    VERSION = "3.3.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab_quality-test_tooling
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.3.0
 platform: ruby
 authors:
 - GitLab Quality
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-17 00:00:00.000000000 Z
+date: 2025-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: climate_control
@@ -227,9 +227,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '7.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -237,9 +234,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '7.3'
 - !ruby/object:Gem::Dependency
   name: amatch
   requirement: !ruby/object:Gem::Requirement
@@ -490,15 +484,20 @@ files:
 - lefthook.yml
 - lib/gitlab_quality/test_tooling.rb
 - lib/gitlab_quality/test_tooling/click_house/client.rb
+- lib/gitlab_quality/test_tooling/code_coverage/README.md
 - lib/gitlab_quality/test_tooling/code_coverage/artifacts.rb
 - lib/gitlab_quality/test_tooling/code_coverage/category_owners.rb
 - lib/gitlab_quality/test_tooling/code_coverage/click_house/category_owners_table.rb
 - lib/gitlab_quality/test_tooling/code_coverage/click_house/coverage_metrics_table.rb
 - lib/gitlab_quality/test_tooling/code_coverage/click_house/table.rb
+- lib/gitlab_quality/test_tooling/code_coverage/click_house/test_file_mappings_table.rb
 - lib/gitlab_quality/test_tooling/code_coverage/coverage_data.rb
 - lib/gitlab_quality/test_tooling/code_coverage/lcov_file.rb
+- lib/gitlab_quality/test_tooling/code_coverage/responsibility_classifier.rb
+- lib/gitlab_quality/test_tooling/code_coverage/responsibility_patterns_config.rb
 - lib/gitlab_quality/test_tooling/code_coverage/rspec_report.rb
 - lib/gitlab_quality/test_tooling/code_coverage/source_file_classifier.rb
+- lib/gitlab_quality/test_tooling/code_coverage/test_file_mapping_data.rb
 - lib/gitlab_quality/test_tooling/code_coverage/test_map.rb
 - lib/gitlab_quality/test_tooling/code_coverage/test_report.rb
 - lib/gitlab_quality/test_tooling/code_coverage/utils.rb