mspec

MSpec guards

platform_is

In some cases, Ruby exhibits different behaviors based on its execution environment. For example, the maximum value of a Fixnum before it is promoted to a Bignum is different in 32-bit and 64-bit platforms. In this cases you can use the
platform_is guard:


  platform_is :wordsize => 32 do
    it "converts numbers to Bignums if they get too big" do
       # 32-bit behaviour goes here
    end
  end 

  platform_is_not :os => :windows do
    it "runs on a real OS" 
      # do something...
    end
  end

This would "do something" on every OS but Windows.

compliant_on/non_compliant_on

Since each Ruby implementation may have its own quirks, you can make use of the compliant_on/non_compliant_on set of guards to make sure that your specs run only on certain implementations:


  non_compliant_on :jruby do
    # some code that works differently in JRuby
  end

Since we're using this project to specify the behavior of MatzRuby (MRI), every compliant_on guard should include :ruby and no non_compliant_on should have it.

ruby_bug

If you know that a certain version of Ruby has a bug and you want to guard against it you can use the ruby_bug guard:


  ruby_bug "some_id_number", "version" do
    it "produces 2 when adding 1 to 1" do
      # CORRECT implementation goes here
      (1 + 1).should == 2
    end
  end

In this case, some_id_number is the number of the reported issue in Ruby's Redmine tracker (because you did create an issue for this, right?). version is the Ruby version you want to guard against, for example:


  ruby_bug "#1337", "1.8.6.110" do
    it "produces 2 when adding 1 to 1" do
      (1+1).should == 2
    end
  end

In this case the issue was reported in Ruby's Redmine as ticket #1337 and this spec will be ignored when the Ruby version is ruby-1.8.6 patchlevel 110.

ruby_version_is

Sometimes the behavior of certain methods will change between different Ruby versions (or revisions). If you're writing specs against several patchlevels or releases you can use the ruby_version_is guard:


  ruby_version_is "" ... "1.9" do
    it "adds two numbers" do
      (1+1).should == 2
    end        
  end

  ruby_version_is "1.9" do
    it "adds two numbers" do
      (1+1).should == 3
    end        
  end

In this case we're assuming that 1 + 1 will equal 2 in every version before 1.9 and that in 1.9 and following versions it will return 3.

big_endian/little_endian

as_superuser

If you need to make sure that you're root before running some of your specs you can use the as_superuser guard:


  as_superuser do
    it "is dangerous" do
      FileUtils.rm_rf("/")
    end
  end

If the user running the specs is not root (UID = 0) the specs will be ignored.

not_supported_on

If a Ruby implementation does not support a certain feature (and probably won't support it in the future) you can use the not_supported_on guard:


  not_supported_on :rubinius do
    it "does some crazy stuff that rubinius people seem to hate" do
    end 
  end

Please note that this guard should only be used when you're almost certain that a feature won't be supported in a Ruby implementation. If you intend to guard a certain case while the implementation supports it you're better off using the MSpec tagging mechanism.

If the implementation you're specifying differs from MRI you should use the non_compliant_on guard.

conflicts_with

If you want to make sure that another class or module is not defined in the current scope before running some tests you can use the conflicts_with guard:


  conflicts_with :SomeWeirdClass do
    it "will not be run if SomeWeirdClass is defined" do
      ...
    end
  end

In this case the spec will run only if SomeWeirdClass is not currently defined. It won't run if SomeWeirdClass is part of the Core classes, if it was required/included or if it was defined earlier.

extended_on

runner_is/runner_is_not

In some cases you might want to make sure that a set of specs runs only under a certain runner (rSpec or MSpec). You can use the runner_is/runner_is_not guards to check this:


  runner_is :rspec do
    it "does something that only runs under rSpec" do
      ...
    end
  end

  runner_is :mspec do
    it "does something that only runs under MSpec" do
      ...
    end
  end

quarantine!

This guard will always return false, which means that the cases inside it will never be run. There are only a handful of acceptable uses for this guard, so please make sure to check on IRC before using it:


  quarantine! do 
    it "will never be run" do
      ...
    end
  end

Also available in: HTML TXT

Wiki