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
