Create RuboCop rule to enforce shared_examples file placement standards

Background & Context

This follow-up issue was created from a discussion in !201411 (merged) where @dstull suggested creating a RuboCop rule to programmatically enforce GitLab's shared examples best practices.

The original merge request involved moving shared examples files from spec/requests/api/graphql/projects/shared_spec.rb to the proper location at spec/support/shared_examples/requests/api/graphql/projects_examples.rb, highlighting the need for automated enforcement of this standard.

Current State

GitLab has established best practices for shared examples placement:

  • Inline shared examples: Can be declared inline if only used in one spec file
  • Reusable shared examples: Should be placed under spec/support/shared_examples/
  • Subfolder organization: Can be placed in subfolders if they apply to specific spec types (features, requests, etc.)
  • Naming convention: Files should have descriptive names ending with _examples.rb

However, there are currently violations of this standard throughout the codebase:

Examples of current violations:

  • spec/lib/feature/shared_spec.rb - Contains regular specs, not shared examples
  • spec/lib/gitlab/health_checks/simple_check_shared.rb - Contains shared context that should be in spec/support/
  • Various *_shared_spec.rb files in different locations

Requested Changes

Create a new RuboCop rule that automatically detects and flags violations of the shared examples placement standards:

  1. Detect misplaced shared examples: Files containing RSpec.shared_examples outside of spec/support/shared_examples/
  2. Detect incorrect naming: Files with shared examples that don't follow the *_examples.rb naming convention
  3. Provide auto-correction: Where possible, suggest the correct file path and name
  4. Handle edge cases: Account for inline shared examples that are acceptable

Detection Logic

The cop should:

  1. Identify shared examples declarations: Look for RSpec.shared_examples, RSpec.shared_examples_for, and RSpec.shared_context(maybe this one)
  2. Check file location: Verify if the file is under spec/support/shared_examples/ or the ee directory for it or if it's inline (single file usage)
  3. Validate naming: Ensure files with shared examples follow the *_examples.rb convention
  4. Cross-reference usage: Determine if shared examples are used across multiple files

Auto-correction Strategy

For files that can be auto-corrected:

  • Suggest moving to spec/support/shared_examples/ with appropriate subfolder structure
  • Recommend proper naming convention

Acceptance Criteria

  • RuboCop cop detects shared examples files in incorrect locations
  • Cop flags files with incorrect naming conventions (*_shared.rb vs *_examples.rb)
  • Cop provides clear, actionable error messages with links to documentation
  • Auto-correction suggests proper file paths when possible
  • Cop distinguishes between inline shared examples (acceptable) and reusable ones (must be in spec/support/)
  • Integration with existing GitLab RuboCop configuration
  • Comprehensive test coverage for the new cop
  • Documentation updates explaining the new rule

Technical Context

Affected Files:

  • rubocop/cop/gitlab/rspec/shared_examples_placement.rb (new)
  • spec/rubocop/cop/gitlab/rspec/shared_examples_placement_spec.rb (new)
  • .rubocop.yml (configuration)
  • Various existing spec files that violate the standard

Implementation Considerations:

Related Issues:

Edited by 🤖 GitLab Bot 🤖