Better organize files under spec

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Currently, files under spec are not really well-organized. Files under spec/support regroup:

  • matchers
  • helpers
  • RSpec config
  • shared contexts
  • shared examples
  • "gitlab_stubs" which really are fixtures

A proposal for a better organization

Matchers

All custom matchers should be placed under spec/support/matchers/. Matchers can be placed in subfolder if they apply to a certain type of specs only (e.g. features, requests etc.) but shouldn't be if they apply to multiple type of specs.

Helpers

All helpers should be be placed under spec/support/helpers/. Helpers can be placed in subfolder if they apply to a certain type of specs only (e.g. features, requests etc.) but shouldn't be if they apply to multiple type of specs.

They should follow the Rails namespacing convention. For instance spec/support/helpers/cycle_analytics_helpers.rb should define:

module Spec
  module Support
    module Helpers
      module CycleAnalyticsHelpers
        def create_commit_referencing_issue(issue, branch_name: random_git_name)
          project.repository.add_branch(user, branch_name, 'master')
          create_commit("Commit for ##{issue.iid}", issue.project, user, branch_name)
        end
      end
    end
  end
end

Helpers should not change the RSpec config. For instance, should not include:

RSpec.configure do |config|
  config.include Spec::Support::Helpers::CycleAnalyticsHelpers
end

RSpec config

RSpec config files are files that change the RSpec config (i.e. RSpec.configure do |config| blocks). They should be placed under spec/support/config/. Each file should be related to a specific domain, e.g. spec/support/config/capybara.rb, spec/support/config/carrierwave.rb etc.

Helpers can be included in the spec/support/config/rspec.rb file. If a helpers module applies only to a certain kind of specs, it should add modifiers to the config.include call. For instance if spec/support/helpers/cycle_analytics_helpers.rb applies to :lib and type: :model specs only, you would write the following:

RSpec.configure do |config|
  config.include Spec::Support::Helpers::CycleAnalyticsHelpers, :lib
  config.include Spec::Support::Helpers::CycleAnalyticsHelpers, type: :model
end

Shared contexts

All shared contexts should be be placed under spec/support/shared_contexts/. Shared contexts can be placed in subfolder if they apply to a certain type of specs only (e.g. features, requests etc.) but shouldn't be if they apply to multiple type of specs. Each file should include only one context and have a descriptive name, e.g. spec/support/shared_contexts/controllers/githubish_import_controller_shared_context.rb.

Shared examples

All shared examples should be be placed under spec/support/shared_examples/. Shared examples can be placed in subfolder if they apply to a certain type of specs only (e.g. features, requests etc.) but shouldn't be if they apply to multiple type of specs. Each file should include only one context and have a descriptive name, e.g. spec/support/shared_examples/controllers/githubish_import_controller_shared_example.rb.

Fixtures

All fixtures should be be placed under spec/fixtures/.

I'd like to have feedback on this proposal. The next step would be to document this, and to perform the actual reorganization of our spec/support files following these guidelines. /cc @dzaporozhets @DouweM @smcgivern @ayufan @rspeicher

Edited by 🤖 GitLab Bot 🤖