Better organize files under `spec`
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