summaryrefslogtreecommitdiff
path: root/spec/README
diff options
context:
space:
mode:
authoreregon <eregon@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2017-05-07 12:01:12 +0000
committereregon <eregon@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2017-05-07 12:01:12 +0000
commit538dcb3044ee5b7b3ff0a7fc787e3779e9a2c57d (patch)
treed46c72a2b57953458b4ab88a8dff198f99c5a33e /spec/README
parente9628d9770a93b8f7d7be5e552e6644cfb10d0e6 (diff)
Update README about ruby/spec
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@58593 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'spec/README')
-rw-r--r--spec/README110
1 files changed, 79 insertions, 31 deletions
diff --git a/spec/README b/spec/README
index c8d17ea..3c32a67 100644
--- a/spec/README
+++ b/spec/README
@@ -1,31 +1,79 @@
-= RubySpec
-
-RubySpec (http://ruby.github.io/rubyspec.github.io/) provides the
-annotation of the Ruby implementation in an executable format. The
-make task `update-rubyspec' retrieves the specification and puts it
-into this directory.
-
-== Directory structure
- spec
- +-- mspec driver library for executing the specification.
- +-- rubyspec
- +-- core specification for core libraries
- | +-- array
- | +-- bignum
- | +-- ...
- |
- +-- fixtures example classes for writing specs
- +-- language specification for Ruby language itself
- +-- library specification for standard libraries
- +-- addrev
- +-- ...
-
-== How to run
-:make target
- verifies all specs.
- $ make test-rubyspec
-:mspec command
- verifies the specified spec.
- $ mspec {language|core|library}
- or
- $ mspec spec/path/to/some_spec.rb
+# ruby/spec
+
+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/rubyspec
+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/rubyspec.
+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`.
+
+## Runing ruby/spec
+
+To run all specs:
+```bash
+make test-rubyspec
+```
+
+Extra arguments can be added via `MSPECOPT`.
+For instance, to show the help:
+```bash
+make test-rubyspec MSPECOPT=-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.
+```bash
+make test-rubyspec MSPECOPT=-j
+```
+
+To run a specific test, add its path to the command:
+```bash
+make test-rubyspec MSPECOPT=spec/rubyspec/language/for_spec.rb
+```
+
+If ruby trunk is your current `ruby` in `$PATH`, you can also run `mspec` directly:
+```bash
+# change ruby to trunk
+ruby -v # => trunk
+spec/mspec/bin/mspec spec/rubyspec/language/for_spec.rb
+```
+
+## ruby/spec and test/
+
+The main difference between a "spec" under spec/rubyspec 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:
+
+```ruby
+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/rubyspec/CONTRIBUTING.md.