API for defining top-level DSL methods?

luislavena · November 1, 2011, 3:37pm

I am in the process of writing a simple DSL inside of rspec, which
defines
some methods that wrap describe/example and augment the metadata, like
capybara’s “feature/scenario” methods. From the excellent RSpec book, I
know how to use Configuration to extend RSpec in a forward-compatible
way,
but it is unclear to me how to define methods on the very top-level, so
I
could write specs like this:

require ‘my_class’
describify ‘something funky’ do; …; end

I looked into how capybara is doing it, and I see that when one includes
‘capybara/rspec’ that causes a class-level method to be defined in the
“global” scope[1]. Is this the preferred way of defining such a method
for
use in RSpec DSLs, or is there a better way? I have been able to use
this
method successfully.

Thanks,
Sam

github.com

teamcapybara/capybara/blob/f41018f884c53633b6744d26ed1d21fb08e3b92f/lib/capybara/rspec/features.rb

module Capybara
  module Features
    def self.included(base)
      base.instance_eval do
        alias :background :before
        alias :scenario :it
      end
    end
  end
end

def self.feature(*args, &block)
  options = if args.last.is_a?(Hash) then args.pop else {} end
  options[:capybara_feature] = true
  options[:type] = :request
  options[:caller] ||= caller
  args.push(options)

  describe(*args, &block)
end

This file has been truncated. show original

Sam_Goldman · November 1, 2011, 4:22pm

On Nov 1, 2011, at 9:34 AM, Sam Goldman wrote:

github.com

teamcapybara/capybara/blob/f41018f884c53633b6744d26ed1d21fb08e3b92f/lib/capybara/rspec/features.rb

module Capybara
  module Features
    def self.included(base)
      base.instance_eval do
        alias :background :before
        alias :scenario :it
      end
    end
  end
end

def self.feature(*args, &block)
  options = if args.last.is_a?(Hash) then args.pop else {} end
  options[:capybara_feature] = true
  options[:type] = :request
  options[:caller] ||= caller
  args.push(options)

  describe(*args, &block)
end

This file has been truncated. show original

We don’t have a formal API, but we should:

github.com/rspec/rspec-core

Add API for managing aliases of `describe`

opened 03:18PM - 01 Nov 11 UTC

closed 02:27PM - 11 Apr 13 UTC

dchelimsky

rspec-core has configuration APIs for managing aliases for `example` (e.g. `it`)… and `shared_examples` (e.g. `it_behaves_like`), but there is no such API for managing aliases for `describe` (which should be renamed to `example_group` and then aliased as `describe` and `context`). As of 2.7, `describe` is available at all levels, but `context` is only available within an example group declaration. I'd propose something along the lines of this: ``` ruby RSpec.configure do |c| c.alias_example_group_to :describe, :top_level => true c.alias_example_group_to :context, :top_level => false end ``` We should also be able to turn off all top-level names if we want, so users concerned with `describe`, `context`, et al bleeding into their code can say: ``` ruby RSpec.describe Thing do it "does something" end ```

In the mean time, just use alias.

Cheers,
David