Testing Ruby¶↑

All the commands below assume that you’re running them from thebuild/ directory made duringBuilding Ruby.

Most commands below should work withGNU make (the default on Linux and macOS),BSD make andNMAKE, except where indicated otherwise.

Test suites¶↑

There are several test suites in the Ruby codebase:

We can run any of the make scriptsin parallel to speed them up.

1. bootstraptest/

   This is a small test suite that runs onMiniruby. We can run it with:

   makebtest

   To run individual bootstrap tests, we can either specify a list of filenames or use the--sets flag in the variableBTESTS:

   makebtestBTESTS="../bootstraptest/test_string.rb ../bootstraptest/test_class.rb"makebtestBTESTS="--sets=string,class"

   To run these tests with verbose logging, we can add-v to theOPTS:

   makebtestOPTS="--sets=string,class -v"

   If we want to run the bootstrap test suite on Ruby (not Miniruby), we can use:

   maketest

   To run these tests with verbose logging, we can add-v to theOPTS:

   maketestOPTS=-v

   (GNU make only) To run a specific file, we can use:

   make ../test/ruby/test_string.rb

   You can use the-n test option to run a specific test with a regex:

   make ../test/ruby/test_string.rb TESTOPTS="-n /test_.*_to_s/"

2. test/

   This is a more comprehensive test suite that runs on Ruby. We can run it with:

   maketest-all

   We can run a specific test file or directory in this suite using theTESTS option, for example:

   make test-all TESTS="../test/ruby/"make test-all TESTS="../test/ruby/test_string.rb"

   We can run a specific test in this suite using theTESTS option, specifying first the file name, and then the test name, prefixed with--name. For example:

   make test-all TESTS="../test/ruby/test_string.rb --name=TestString#test_to_s"

   To run these tests with verbose logging, we can add-v toTESTS:

   make test-all TESTS=-v

   We can display the help of theTESTS option:

   make test-all TESTS=--help

   We can run all the tests intest/,bootstraptest/ andspec/ (thespec/ is explained in a later section) all together with:

   makecheck

3. spec/ruby

   This is a test suite defined inthe Ruby spec repository, and is periodically mirrored into thespec/ruby directory of this repository. It tests the behavior of the Ruby programming language. We can run this using:

   maketest-spec

   We can run a specific test file or directory in this suite using theSPECOPTS option, for example:

   make test-spec SPECOPTS="../spec/ruby/core/string/"make test-spec SPECOPTS="../spec/ruby/core/string/to_s_spec.rb"

   To run a specific test, we can use the--example flag to match against the test name:

   make test-spec SPECOPTS="../spec/ruby/core/string/to_s_spec.rb --example='returns self when self.class == String'"

   To run these specs with verbose logging, we can add-v to theSPECOPTS:

   make test-spec SPECOPTS="../spec/ruby/core/string/to_s_spec.rb -Vfs"

   (GNU make only) To run a ruby-spec file or directory, we can use

   make ../spec/ruby/core/string/to_s_spec.rb

4. spec/bundler

   The bundler test suite is defined inthe RubyGems repository, and is periodically mirrored into thespec/ruby directory of this repository. We can run this using:

   maketest-bundler

   To run a specific bundler spec file, we can useBUNDLER_SPECS as follows:

   make test-bundler BUNDLER_SPECS=commands/exec_spec.rb

Troubleshooting¶↑

Running test suites on s390x CPU Architecture¶↑

If we see failing tests related to the zlib library on s390x CPU architecture, we can run the test suites withDFLTCC=0 to pass:

DFLTCC=0 make check

The failures can happen with the zlib library applying the patchmadler/zlib#410 to enable the deflate algorithm producing a different compressed byte stream. We manage this issue at[ruby-core:114942][Bug #19909].