ruby/spec
David Rodríguez a3882dc565 Remove test dependency on logger
I think logger is only used to figure out which methods need to be made
noops in order to silence webrick during tests.

However, it seems possible to do the same using webrick's builtin logger
and the current method does not seem even correct since it's not
guaranteed that the logger gem and webrick's logger will use the same
methods.
2025-01-14 12:24:37 +09:00
..
bin Use directory structure and GEM_HOME for ruby-core repository 2024-12-12 14:43:07 +09:00
bundler Remove test dependency on logger 2025-01-14 12:24:37 +09:00
lib * append newline at EOF. [ci skip] 2024-12-12 05:43:17 +00:00
mspec Launchable: Start recording test-spec results (#12302) 2024-12-12 16:32:35 +09:00
ruby [Feature #6012] Extend source_location for end position and columns 2025-01-09 20:21:41 +09:00
syntax_suggest [ruby/syntax_suggest] Resolve to lint failure of standardrb 2025-01-10 05:38:39 +00:00
bundled_gems.mspec Convert ostruct to openstruct 2025-01-08 17:12:19 +09:00
bundled_gems_spec.rb Added logger dependency for Bundler's example 2025-01-10 10:19:39 +09:00
default.mspec Convert ostruct to openstruct 2025-01-08 17:12:19 +09:00
mmtk.mspec [ruby/mmtk] Add MMTk test exclusions for Ruby CI 2024-12-05 20:12:45 +00:00
README.md [DOC] Update to use SPECOPTS instead of MSPECOPT 2023-08-12 12:33:05 +09:00

spec/bundler

spec/bundler is rspec examples for bundler library (lib/bundler.rb, lib/bundler/*).

Running spec/bundler

To run rspec for bundler:

make test-bundler

or run rspec with parallel execution:

make test-bundler-parallel

If you specify BUNDLER_SPECS=foo/bar_spec.rb then only spec/bundler/foo/bar_spec.rb will be run.

spec/ruby

ruby/spec (https://github.com/ruby/spec/) is a test suite for the Ruby language.

Once a month, @eregon merges the in-tree copy under spec/ruby with the upstream repository, preserving the commits and history. The same happens for other implementations such as JRuby and TruffleRuby.

Feel welcome to modify the in-tree spec/ruby. This is the purpose of the in-tree copy, to facilitate contributions to ruby/spec for MRI developers.

New features, additional tests for existing features and regressions tests are all welcome in ruby/spec. There is very little behavior that is implementation-specific, as in the end user programs tend to rely on every behavior MRI exhibits. In other words: If adding a spec might reveal a bug in another implementation, then it is worth adding it. Currently, the only module which is MRI-specific is RubyVM.

Changing behavior and versions guards

Version guards (ruby_version_is) must be added for new features or features which change behavior or are removed. This is necessary for other Ruby implementations to still be able to run the specs and contribute new specs.

For example, change:

describe "Some spec" do
  it "some example" do
    # Old behavior for Ruby < 2.7
  end
end

to:

describe "Some spec" do
  ruby_version_is ""..."2.7" do
    it "some example" do
      # Old behavior for Ruby < 2.7
    end
  end

  ruby_version_is "2.7" do
    it "some example" do
      # New behavior for Ruby >= 2.7
    end
  end
end

See spec/ruby/CONTRIBUTING.md for more documentation about guards.

To verify specs are compatible with older Ruby versions:

cd spec/ruby
$RUBY_MANAGER use 2.4.9
../mspec/bin/mspec -j

Running ruby/spec

To run all specs:

make test-spec

Extra arguments can be added via SPECOPTS. For instance, to show the help:

make test-spec SPECOPTS=-h

You can also run the specs in parallel, which is currently experimental. It takes around 10s instead of 60s on a quad-core laptop.

make test-spec SPECOPTS=-j

To run a specific test, add its path to the command:

make test-spec SPECOPTS=spec/ruby/language/for_spec.rb

If ruby trunk is your current ruby in $PATH, you can also run mspec directly:

# change ruby to trunk
ruby -v # => trunk
spec/mspec/bin/mspec spec/ruby/language/for_spec.rb

ruby/spec and test/

The main difference between a "spec" under spec/ruby/ and a test under test/ is that specs are documenting what they test. This is extremely valuable when reading these tests, as it helps to quickly understand what specific behavior is tested, and how a method should behave. Basic English is fine for spec descriptions. Specs also tend to have few expectations (assertions) per spec, as they specify one aspect of the behavior and not everything at once. Beyond that, the syntax is slightly different but it does the same thing: assert_equal 3, 1+2 is just (1+2).should == 3.

Example:

describe "The for expression" do
  it "iterates over an Enumerable passing each element to the block" do
    j = 0
    for i in 1..3
      j += i
    end
    j.should == 6
  end
end

For more details, see spec/ruby/CONTRIBUTING.md.

spec/syntax_suggest

Running spec/syntax_suggest

To run rspec for syntax_suggest:

make test-syntax-suggest

If you specify SYNTAX_SUGGEST_SPECS=foo/bar_spec.rb then only spec/syntax_suggest/foo/bar_spec.rb will be run.