Clean up documentation leftovers for trigger_inclusion behaviour

[pirj]

Fixes #2775
Related:

• Remove shared_context_metadata_behavior config option and make apply_to_host_groups the default #2834
• Reconsider shared_context_metadata_behavior #2832
• Auto-included shared contexts are not subject to the same scoping rules that manually included ones are #1762

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

⚠️ It is also order-dependent, see this ticket.

[benoittgt]

I love those short examples @pirj :)