Need help with spec?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

474 Stars 370 Forks MIT License 13.2K Commits 11 Opened issues


The Ruby Spec Suite aka ruby/spec

Services available


Need anything else?

Contributors list

The Ruby Spec Suite

Actions Build Status Gitter

The Ruby Spec Suite, abbreviated

, is a test suite for the behavior of the Ruby programming language.

Description and Motivation

It is not a standardized specification like the ISO one, and does not aim to become one. Instead, it is a practical tool to describe and test the behavior of Ruby with code.

Every example code has a textual description, which presents several advantages:

  • It is easier to understand the intent of the author
  • It documents how recent versions of Ruby should behave
  • It helps Ruby implementations to agree on a common behavior

The specs are written with syntax similar to RSpec 2. They are run with MSpec, the purpose-built framework for running the Ruby Spec Suite. For more information, see the MSpec project.

The specs describe the language syntax, the core library, the standard library, the C API for extensions and the command line flags. The language specs are grouped by keyword while the core and standard library specs are grouped by class and method.

ruby/spec is known to be tested in these implementations for every commit: * MRI on 30 platforms and 4 versions * JRuby for both 1.7 and 9.x * TruffleRuby * Opal * Artichoke

ruby/spec describes the behavior of Ruby 2.6 and more recent Ruby versions. More precisely, every latest stable MRI release should pass all specs of ruby/spec (2.6.x, 2.7.x, 3.0.x, etc), and those are tested in CI.

Synchronization with Ruby Implementations

The specs are synchronized both ways around once a month by @eregon between ruby/spec, MRI, JRuby and TruffleRuby, using this script. Each of these repositories has a full copy of the specs under

to ease editing specs. Any of these repositories can be used to add or edit specs, use what is most convenient for you.

For testing the development version of a Ruby implementation, one should always test against that implementation's copy of the specs under

, as that's what the Ruby implementation tests against in their CI. Also, this repository doesn't always contain the latest spec changes from MRI (it's synchronized monthly), and does not contain tags (specs marked as failing on that Ruby implementation). Running specs on a Ruby implementation can be done with:
$ cd ruby_implementation/spec/ruby
# Add ../ruby_implementation/bin in PATH, or pass -t /path/to/bin/ruby
$ ../mspec/bin/mspec

Specs for old Ruby versions

For older specs try these commits: * Ruby 2.0.0-p647 - Suite using MSpec (may encounter 2 failures) * Ruby 2.1.9 - Suite using MSpec * Ruby 2.2.10 - Suite using MSpec * Ruby 2.3.8 - Suite using MSpec * Ruby 2.4.10 - Suite using MSpec * Ruby 2.5.9 - Suite using MSpec

Running the specs

First, clone this repository:

$ git clone

Then move to it:

$ cd spec

Clone MSpec:

$ git clone ../mspec

And run the spec suite:

$ ../mspec/bin/mspec

This will execute all the specs using the executable named

on your current PATH.

Running Specs with a Specific Ruby Implementation

Use the

option to specify the Ruby implementation with which to run the specs. The argument is either a full path to the Ruby binary, or an executable in
$ ../mspec/bin/mspec -t /path/to/some/bin/ruby

Running Selected Specs

To run a single spec file, pass the filename to

$ ../mspec/bin/mspec core/kernel/kind_of_spec.rb

You can also pass a directory, in which case all specs in that directories will be run:

$ ../mspec/bin/mspec core/kernel

Finally, you can also run them per group as defined in

. The following command will run all language specs:
$ ../mspec/bin/mspec :language

In similar fashion, the following commands run the respective specs:

$ ../mspec/bin/mspec :core
$ ../mspec/bin/mspec :library
$ ../mspec/bin/mspec :capi

Sanity Checks When Running Specs

A number of checks for various kind of "leaks" (file descriptors, temporary files, threads, subprocesses,

, global encodings, top-level constants) can be enabled with
$ CHECK_LEAKS=true ../mspec/bin/mspec

New top-level constants should only be introduced when needed or follow the pattern

such as
module StringSpecs
. Other constants used for testing should be nested under such a module.

Exceptions to these rules are contained in the file

. MSpec can automatically add new top-level constants in this file with:
$ CHECK_LEAKS=save mspec ../mspec/bin/mspec file

Contributing and Writing Specs

See for documentation about contributing and writing specs (guards, matchers, etc).


These command-line executables are needed to run the specs.

  • echo
  • stat
  • find
    , not needed on Windows)

The file

is required for socket specs (package
on Debian, not needed on Windows).

Socket specs from rubysl-socket

Most specs under

were imported from the rubysl-socket project. The 3 copyright holders of rubysl-socket, Yorick Peterse, Chuck Remes and Brian Shirai, agreed to relicense those specs under the MIT license in ruby/spec.

History and RubySpec

This project was originally born from Rubinius tests being converted to the spec style. The revision history of these specs is available here. These specs were later extracted to their own project, RubySpec, with a specific vision and principles. At the end of 2014, Brian Shirai, the creator of RubySpec, decided to end RubySpec. A couple months later, the different repositories were merged and the project was revived. On 12 January 2016, the name was changed to "The Ruby Spec Suite" for clarity and to let the RubySpec ideology rest in peace.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.