Clean up documentation leftovers for trigger_inclusion behaviour
Created by: pirj
Fixes #2775 Related:
- #2834
- #2832 (closed)
- #1762 (closed)
To sum it all up, the current behavior (apply_to_host_groups
) is:
1.1. Configuration-level methods (include
, extend
, prepend
, include_context
, before
, after
, around
) are tagged with metadata that is matched against example group metadata (and example metadata, as an example has a singleton example group), and are included. E.g.:
RSpec.configuration do |config|
config.before(:example, litter_env: true) do
ENV['litter'] = 'true'
end
end
RSpec.describe do
it 'survives litter flood', :litter_env do
expect(ENV['litter']).to eq('true')
end
end
1.2. Example group-level methods' (shared_examples
/shared_examples_for
, shared_context
) metadata is applied to host groups that explicitly include them. E.g.:
RSpec.describe do
shared_context 'in the wild', cold: true do
let(:temp) { -30 }
end
context 'winter' do
include_context 'in the wild'
it 'is cold' do |example|
expect(example.metadata[:cold]).to be(true)
expect(temp).to eq(-30)
end
end
end
1.3. Example group-level methods' (shared_examples
/shared_examples_for
, shared_context
) do not include shared groups to example groups based on matching metadata. E.g.:
RSpec.describe do
shared_context 'done', done: true do
before do
ENV['done'] = 'done'
end
end
it 'is done', :done do
expect(ENV['done']).to be(nil)
end
end
1.4 Example group-level hook methods are executed for examples with matching metadata. E.g.:
RSpec.describe do
let(:pocket) { [] }
before(:example, profit: true) do
pocket << :penny
end
it 'is empty' do
expect(pocket).to be_empty
end
it 'is full', :profit do
expect(pocket).to contain_exactly(:penny)
end
end
Just to avoid any confusion:
2.1. Configuration-level methods shared_context
/shared_examples
/shared_examples_for
are not defined
2.2. Configuration-level methods include_examples
/it_behaves_like
are not defined
2.3. Example group-level include_context
/include_examples
/it_behaves_like
(as opposed to configuration-level counterparts) do not accept metadata, but rather parameters that are passed to the included shared group:
RSpec.describe do
shared_context 'foo' do |var:|
let(:foo) { var }
end
include_context 'foo', var: :bar
it 'foo is bar' do
expect(foo).to eq(:bar)
end
end
Quite obvious but confused me:
3.1. Included example groups override memoized helpers defined in the including example group:
RSpec.describe "open-close" do
let(:open) { false }
shared_context "is open" do
let(:open) { true }
end
include_context "is open"
it 'overrides open' do
expect(open).to be(true)
end
end