rubyspec

h1. Guards

h2. Overview

The RubySpec project intends to provide a complete and exhaustive specification of the Ruby language and its libraries.

There is a single _standard_ implementation of Ruby. The _standard_ includes the stable, released versions available from http://ruby-lang.org. At present, the _standard_ is 1.8.6, 1.8.7, and 1.9.1. Collectively, the _standard_ is often referred to as MatzRuby or MRI.

The challenge for RubySpec is to correctly spec the different behaviors across versions, platforms, and implementations. To do this, the RubySpecs depend on _guards_ provided by MSpec. Guards are methods that may or may not take arguments and operate by yielding to a block if certain conditions are true. If the conditions for the guard are not true, the guard method does not yield to the block and the specs contained in the block are not run.

The guards serve two functions: 1) controlling which specs are run; 2) documenting the specs. The documentation function of the guards is as important for RubySpec as controlling which specs are run. Additionally, the guard structure itself was chosen to be visually and conceptually similar to the describe/it blocks in the specs.

The guard blocks should be placed around @describe@ or @it@ blocks. Guards should _not_ be placed inside @it@ blocks. Guards should rarely, if ever, be placed inside @before@ or @after@ actions.

There are five categories of guards:

# versions

# platforms

# bugs

# implementations

# environments

The specific guards in each of these categories are explained below.

h3. 1. Versions

Different versions of Ruby have same methods that behave differently. That sounds circular, but it is the essence of software versions. To handle different version behaviors, MSpec provides the ruby_version_is guard.

ruby_version_is "1.8.6.114" do

  it "returns true" do

  end

end

ruby_version_is "1.8" .. "1.8.6" do

  it "returns nil" do

  end

end

ruby_version_is "" ... "1.9" do

  it "returns false" do

  end

end

The ruby_version_is guard takes one argument that may be a string or a range of two strings. The format of the string is A.B.C.D, where:

* A is the major version

* B is the minor version

* C is the tiny (teeny) version

* D is the patchlevel

The string is converted to a number on which comparisons between versions can be made so that, for instance, "1.8.6.37" is less than "1.8.6.112".

The range behaves as expected, respecting #exclude_end?. In the example above, "" ... "1.9" means every version *before* 1.9.

h3. 2. Platforms

A single version of Ruby may have different behaviors depending on the platform on which it runs. MSpec provides several guards for these situations:

# big_endian

# little_endian

# platform_is

# platform_is_not

The @big_endian@ guard yields to the block if the platform is big endian. Likewise for the @little_endian@ guard.

The platform_is and platform_is_not guards are more complex. As their names suggest, they are inverses.

platform_is :linux, :bsd do

  it "opens the file" do

  end

end

The guard above will yield if RUBY_PLATFORM matches either "linux" OR "bsd".

platform_is :linux, :wordsize => 32 do

  it "opens the file" do

  end

end

The guard above will yield if RUBY_PLATFORM matches "linux" AND the processor word size is 32-bit.

platform_is_not :windows, :wordsize => 32 do

  it "opens the file" do

  end

end

The guard above will yield if RUBY_PLATFORM does not matches "windows" AND the processor word size is not 32-bit.

Special functionality exists for matching :windows and :java as platforms. For details, refer to the MSpec source.

platform_is :os => [:darwin, :bsd] do

  it "opens the file" do

  end

end

The guard above will yield if Config::CONFIG['host_os'] matches either "darwin" OR "BSD". If Config::CONFIG['host_os'] is not set in rbconfig, the :os parameters will be matched against RUBY_PLATFORM instead.

h3. 3. Bugs

Sometimes a bug is discovered in the _standard_. In this case, we do two things:

# File a ticket on the "bug tracker":http://redmine.ruby-lang.org/ to find out if the suspected behavior is actually considered a bug.

# Add a @ruby_bug@ guard that wraps the spec showing what is considered to be the _correct_ behavior.

ruby_bug "#5555", "1.8.6.114" do

  it "returns the sum" do

    (1 + 1).should == 2

  end

end

The @ruby_bug@ guard serves three purposes:

# It documents that there is a bug in a particular version of the standard and refers to the ticket for that bug.

# It provides the correct behavior description for all implementations

# It prevents the spec for the correct behavior from running (and failing) on versions of the _standard_ implementation that have the bug and have already been released.

h3. 4. Implementations

# compliant_on

# not_compliant_on

# not_supported_on

# deviates_on

# extended_on

h3. 5. Environments

# runner_is

# runner_is_not

# as_superuser

# conflicts_with

# quarantine!