spec/README.md

   1 # spec/bundler
   2
   3 spec/bundler is rspec examples for bundler library (`lib/bundler.rb`, `lib/bundler/*`).
   4
   5 ## Running spec/bundler
   6
   7 To run rspec for bundler:
   8
   9 ```bash
  10 make test-bundler
  11 ```
  12
  13 or run rspec with parallel execution:
  14
  15 ```bash
  16 make test-bundler-parallel
  17 ```
  18
  19 If you specify `BUNDLER_SPECS=foo/bar_spec.rb` then only `spec/bundler/foo/bar_spec.rb` will be run.
  20
  21 # spec/ruby
  22
  23 ruby/spec (https://github.com/ruby/spec/) is
  24 a test suite for the Ruby language.
  25
  26 Once a month, @eregon merges the in-tree copy under spec/ruby
  27 with the upstream repository, preserving the commits and history.
  28 The same happens for other implementations such as JRuby and TruffleRuby.
  29
  30 Feel welcome to modify the in-tree spec/ruby.
  31 This is the purpose of the in-tree copy,
  32 to facilitate contributions to ruby/spec for MRI developers.
  33
  34 New features, additional tests for existing features and
  35 regressions tests are all welcome in ruby/spec.
  36 There is very little behavior that is implementation-specific,
  37 as in the end user programs tend to rely on every behavior MRI exhibits.
  38 In other words: If adding a spec might reveal a bug in
  39 another implementation, then it is worth adding it.
  40 Currently, the only module which is MRI-specific is `RubyVM`.
  41
  42 ## Changing behavior and versions guards
  43
  44 Version guards (`ruby_version_is`) must be added for new features or features
  45 which change behavior or are removed. This is necessary for other Ruby implementations
  46 to still be able to run the specs and contribute new specs.
  47
  48 For example, change:
  49
  50 ```ruby
  51 describe "Some spec" do
  52   it "some example" do
  53     # Old behavior for Ruby < 2.7
  54   end
  55 end
  56 ```
  57
  58 to:
  59
  60 ```ruby
  61 describe "Some spec" do
  62   ruby_version_is ""..."2.7" do
  63     it "some example" do
  64       # Old behavior for Ruby < 2.7
  65     end
  66   end
  67
  68   ruby_version_is "2.7" do
  69     it "some example" do
  70       # New behavior for Ruby >= 2.7
  71     end
  72   end
  73 end
  74 ```
  75
  76 See `spec/ruby/CONTRIBUTING.md` for more documentation about guards.
  77
  78 To verify specs are compatible with older Ruby versions:
  79
  80 ```bash
  81 cd spec/ruby
  82 $RUBY_MANAGER use 2.4.9
  83 ../mspec/bin/mspec -j
  84 ```
  85
  86 ## Running ruby/spec
  87
  88 To run all specs:
  89
  90 ```bash
  91 make test-spec
  92 ```
  93
  94 Extra arguments can be added via `SPECOPTS`.
  95 For instance, to show the help:
  96
  97 ```bash
  98 make test-spec SPECOPTS=-h
  99 ```
 100
 101 You can also run the specs in parallel, which is currently experimental.
 102 It takes around 10s instead of 60s on a quad-core laptop.
 103
 104 ```bash
 105 make test-spec SPECOPTS=-j
 106 ```
 107
 108 To run a specific test, add its path to the command:
 109
 110 ```bash
 111 make test-spec SPECOPTS=spec/ruby/language/for_spec.rb
 112 ```
 113
 114 If ruby trunk is your current `ruby` in `$PATH`, you can also run `mspec` directly:
 115
 116 ```bash
 117 # change ruby to trunk
 118 ruby -v # => trunk
 119 spec/mspec/bin/mspec spec/ruby/language/for_spec.rb
 120 ```
 121
 122 ## ruby/spec and test/
 123
 124 The main difference between a "spec" under `spec/ruby/` and
 125 a test under `test/` is that specs are documenting what they test.
 126 This is extremely valuable when reading these tests, as it
 127 helps to quickly understand what specific behavior is tested,
 128 and how a method should behave. Basic English is fine for spec descriptions.
 129 Specs also tend to have few expectations (assertions) per spec,
 130 as they specify one aspect of the behavior and not everything at once.
 131 Beyond that, the syntax is slightly different but it does the same thing:
 132 `assert_equal 3, 1+2` is just `(1+2).should == 3`.
 133
 134 Example:
 135
 136 ```ruby
 137 describe "The for expression" do
 138   it "iterates over an Enumerable passing each element to the block" do
 139     j = 0
 140     for i in 1..3
 141       j += i
 142     end
 143     j.should == 6
 144   end
 145 end
 146 ```
 147
 148 For more details, see `spec/ruby/CONTRIBUTING.md`.
 149
 150 # spec/syntax_suggest
 151
 152 ## Running spec/syntax_suggest
 153
 154 To run rspec for syntax_suggest:
 155
 156 ```bash
 157 make test-syntax-suggest
 158 ```
 159
 160 If you specify `SYNTAX_SUGGEST_SPECS=foo/bar_spec.rb` then only `spec/syntax_suggest/foo/bar_spec.rb` will be run.