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

Ideally, all Ruby implementations would have exactly the same behaviors. This is not realistically possible given differences in the underlying technology, for instance, whether the process @fork@ facility is available.

It should be obvious, but it bears repeating, that in a specification for a standard, there should be an absolute minimum of incompatible behavior. These guards are not provided to make it easy to be inconsistent. Rather, they are provided to make specifying a single standard as simple as possible, recognizing that 100% conformity is an impossible ideal.

Recall that the purpose of the guards are to _both_ control which specs are run AND document the specs. There are four distinct situations covered by the five guards below. Each of the guards documents this difference.

# compliant_on

# not_compliant_on

# not_supported_on

# deviates_on

# extended_on

The @compliant_on@ and not_compliant_on guards are inverses. They document that the enclosed spec passes or does not pass on the listed implementations or platforms.

compliant_on :jruby, :rubinius do

  it "returns true" do

  end

end

The spec above will ONLY run on the _standard_, JRuby, or Rubinius. The @compliant_on@ guard will not run on any other implementation or platform except the ones listed.

There is no need to list :ruby or :ruby19 for this guard. There is only one standard and specs are _always_ expected run correctly on the _standard_. If there is version-specific behavior or a bug in the _standard_, use the @ruby_bug@ or ruby_version_is guard instead.

not_compliant_on :rubinius do

  it "returns false" do

  end

end

The spec above will run on EVERY implementation except Rubinius.

It should be obvious that the @compliant_on@ guard is more convenient when the number of implementations that conform to the standard is small compared to the total number of implementations. The not_compliant_on guard is useful when the number of non-conforming implementations is small.

h3. 5. Environments

The following guards are broadly grouped by their relation to how the specs are run. This is referred to as the spec _environment_. It includes guards for which runner (e.g. RSpec or MSpec) is executing the specs, which classes are loaded when the specs run, and whether the process running the specs has superuser privileges.

# runner_is

# runner_is_not

# conflicts_with

# as_superuser

# quarantine!

The quarantine! guard will never yield to the block, so the specs inside the guard will not run. This guard is only used to temporarily disable a guard that is causing the _standard_ to fail severely (for example, by causing a segfault) AND the correctness of the spec is suspect. The guard allows the spec to be investigated but not cause any failures.

If a spec exposes a bug that is causing a segfault, the @ruby_bug@ guard should be used.

quarantine! do 

  it "does something that causes a segfault" do

  end

end