Skip to content

Commit bb513b7

Browse files
soulcuttersoulcutter
committed
Merge pull request #1093 from rspec/rails-4-schema-changes-docs
Rails 4 schema changes docs
2 parents 3d607b4 + 7f51292 commit bb513b7

File tree

4 files changed

+170
-106
lines changed

4 files changed

+170
-106
lines changed

‎README.md

Lines changed: 11 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -57,43 +57,23 @@ be run via `bin/rspec`:
5757
bundle binstubs rspec-core
5858
```
5959

60-
### Upgrade note
60+
### Upgrade Note
6161

62-
For detailed information on the RSpec 3.x upgrade process see the
62+
For detailed information on the general RSpec 3.x upgrade process see the
6363
[RSpec Upgrade docs](https://relishapp.com/rspec/docs/upgrade).
6464

65-
There are two particular `rspec-rails` specific changes to be aware of:
66-
67-
> File-type inference disabled by default
68-
69-
Previously we automatically inferred spec type from a file location, this
70-
was a surprising behaviour for new users and undesirable for some veteran users
71-
so from RSpec 3 onwards this behaviour must be explicitly opted into with:
72-
73-
```Ruby
74-
RSpec.configure do |config|
75-
config.infer_spec_type_from_file_location!
76-
end
77-
```
78-
79-
This change was made to accomplish our general goals of acting with the principle
80-
of least surprise and removing magic from RSpec. See [the directory structure
81-
documentation](https://www.relishapp.com/rspec/rspec-rails/v/3-0/docs/directory-structure)
82-
for more details.
83-
84-
The other `rspec-rails` specific change is:
65+
There are three particular `rspec-rails` specific changes to be aware of:
8566

86-
> The default helper files created in RSpec 3.x have changed
67+
1. [The default helper files created in RSpec 3.x have changed](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade#default-helper-files)
68+
2. [File-type inference disabled by default](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade#file-type-inference-disabled)
69+
3. [Rails 4.x `ActiveRecord::Migration` pending migration checks](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade#pending-migration-checks)
8770

88-
In prior versions, only a single `spec_helper.rb` file was generated. This file
89-
has been moved to `rails_helper.rb`. The new `spec_helper.rb` is the same
90-
standard helper generated by running `rspec --init`.
71+
Please see the [RSpec Rails Upgrade
72+
docs](https://www.relishapp.com/rspec/rspec-rails/docs/upgrade) for full
73+
details.
9174

92-
This change was made to accomplish two general goals:
93-
94-
- Keep the installation process in sync with regular RSpec changes
95-
- Provide an out-of-the-box way to avoid loading Rails for those specs that do
96-
not require it
75+
**NOTE:** Generators run in RSpec 3.x will now require `rails_helper` instead
76+
of `spec_helper`.
9777

9878
### Upgrading an Existing App
9979

@@ -142,9 +122,6 @@ switch to the new helpers:
142122

143123
### Generators
144124

145-
**NOTE:** Generators run in RSpec 3.x will use the `rails_helper` by default.
146-
See the above [upgrade notes](#upgrade-note) about this change.
147-
148125
Once installed, RSpec will generate spec files instead of Test::Unit test files
149126
when commands like `rails generate model` and `rails generate controller` are
150127
used.

‎features/.nav

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1+
- upgrade:
2+
- from_1x_to_2x.md (From rspec-rails-1.x to rspec-rails-2)
13
- GettingStarted.md (Start from scratch)
24
- Generators.md (Generators)
35
- Transactions.md
46
- Changelog.md
5-
- Upgrade.md
67
- RailsVersions.md (Rails versions)
78
- directory_structure.feature
89
- model_specs:

‎features/upgrade/README.md

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Upgrading from rspec-rails-2.x to rspec-rails-3
2+
3+
For detailed information on the general RSpec 3.x upgrade process see the [RSpec
4+
Upgrade docs](https://relishapp.com/rspec/docs/upgrade).
5+
6+
There are several changes specific to `rspec-rails` to be aware of:
7+
8+
- [Default helper files created in RSpec 3.x have changed](#default-helper-files)
9+
- [File-type inference disabled by default](#file-type-inference-disabled)
10+
- [Rails 4.x `ActiveRecord::Migration` pending migration checks](#pending-migration-checks)
11+
12+
<a name="default-helper-files"></a>
13+
## Default helper files created in RSpec 3.x have changed
14+
15+
In prior versions, only a single `spec_helper.rb` file was generated. This file
16+
has been moved to `rails_helper.rb`. The new `spec_helper.rb` is the same
17+
standard helper generated by running `rspec --init`.
18+
19+
This change was made to accomplish two general goals:
20+
21+
- Keep the installation process in sync with regular RSpec changes
22+
23+
- Provide an out-of-the-box way to avoid loading Rails for those specs that do
24+
not require it
25+
26+
<a name="generators"></a>
27+
### Generators
28+
29+
Generators run in RSpec 3.x will require `rails_helper` and not `spec_helper`.
30+
31+
<a name="upgrading-an-existing-app"></a>
32+
### Upgrading an Existing App
33+
34+
For most existing apps, one of the following upgrade paths is sufficient to
35+
switch to the new helpers:
36+
37+
#### I need to move things over in stages
38+
39+
1. Create a new `rails_helper.rb` with the following content:
40+
41+
```ruby
42+
require 'spec_helper'
43+
```
44+
45+
2. As necessary, replace `require 'spec_helper'` with `require 'rails_helper'`
46+
in the specs.
47+
48+
3. When ready, move any Rails specific code and setup from `spec_helper.rb` to
49+
`rails_helper.rb`.
50+
51+
#### I'm ready to just switch completely
52+
53+
1. Move the existing `spec_helper.rb` to `rails_helper.rb`:
54+
55+
```ruby
56+
git mv spec/spec_helper.rb spec/rails_helper.rb
57+
```
58+
59+
2. Run the installation rake task opting to not replace `rails_helper.rb`:
60+
61+
```console
62+
$ bin/rails generate rspec:install
63+
create .rspec
64+
exist spec
65+
create spec/spec_helper.rb
66+
conflict spec/rails_helper.rb
67+
Overwrite my_app/spec/rails_helper.rb? (enter "h"for help) [Ynaqdh] n
68+
skip spec/rails_helper.rb
69+
```
70+
71+
3. Move any non-Rails RSpec configurations and customizations from your
72+
`rails_helper.rb` to `spec_helper.rb`.
73+
74+
4. Find/replace instances of `require 'spec_helper'` with
75+
`require 'rails_helper'` in any specs which rely on Rails.
76+
77+
<a name="file-type-inference-disabled"></a>
78+
## File-type inference disabled by default
79+
80+
Previously we automatically inferred spec type from a file location, this
81+
was a surprising behaviour for new users and undesirable for some veteran users
82+
so from RSpec 3 onwards this behaviour must be explicitly opted into with:
83+
84+
```Ruby
85+
RSpec.configure do |config|
86+
config.infer_spec_type_from_file_location!
87+
end
88+
```
89+
90+
This change was made to accomplish our general goals of acting with the principle
91+
of least surprise and making RSpec configuration more explicit. See [the
92+
directory structure documentation](https://www.relishapp.com/rspec/rspec-rails/v/3-0/docs/directory-structure) for more details.
93+
94+
<a name="pending-migration-checks"></a>
95+
## Rails 4.x `ActiveRecord::Migration` pending migration checks
96+
97+
If you are not using `ActiveRecord` you do not need to worry about these
98+
settings.
99+
100+
Users of Rails 4.x can now take advantage of improved schema migration and sync
101+
abilities. Prior to RSpec 3, users were required to manually run migrations in
102+
both the development and test environments. Additionally, the behavior differed
103+
depending on if the specs were run via `rake` or via the standalone `rspec`
104+
command.
105+
106+
With the release of Rails 4, new APIs have been exposed on
107+
`ActiveRecord::Migration`. This allows RSpec to take advantage of these new
108+
standard migration checks, mirroring behavior across the board.
109+
110+
- Rails 4.0.x
111+
112+
Add the following to the top of the `rails_helper` file after Rails has
113+
been required:
114+
115+
```ruby
116+
ActiveRecord::Migration.check_pending!
117+
```
118+
119+
This will raise an exception if there are any pending schema changes. Users
120+
will still be required to manually keep the development and test
121+
environments in sync.
122+
123+
- Rails 4.1+
124+
125+
With this release there was an exciting new feature. Users no longer need
126+
to keep the development and test environments in sync. To take advantage of
127+
this add the following to the top of the `rails_helper` file after Rails
128+
has been required:
129+
130+
```ruby
131+
ActiveRecord::Migration.maintain_test_schema!
132+
```
133+
134+
What this does is that rather than just raising when the test schema has
135+
pending migrations, Rails will try to load the schema. An exception will
136+
now only be raised if there are pending migrations afterwards the schema
137+
has been loaded.
138+
139+
There are a few caveates to be aware of when using this:
140+
141+
- Migrations still need to be run manually; although now this only has to
142+
be done in the 'development' environment
143+
- An exception will be raised If the schema has not been initialized. The
144+
exception will provide instructions stating `rake db:migrate` needs to
145+
be run.
146+
147+
It is possible to opt-out of checking for pending migrations. Since this is
148+
actually a feature of Rails, the change needs to be done as part of the Rails
149+
configuration. To do this, add the following to your
150+
`config/environments/test.rb` file:
151+
152+
```ruby
153+
config.active_record.maintain_test_schema = false
154+
```
155+
156+
New RSpec projects don't need to worry about these commands as the `rails
157+
generate rspec:install` will add them automatically.

‎features/Upgrade.md renamed to ‎features/upgrade/from_1x_to_2x.md

Lines changed: 0 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,3 @@
1-
# Upgrading from rspec-rails-2.x to rspec-rails-3
2-
3-
For detailed information on the RSpec 3.x upgrade process see the [RSpec Upgrade
4-
docs](https://relishapp.com/rspec/docs/upgrade).
5-
6-
There is another `rspec-rails` specific change to be aware of:
7-
8-
```text
9-
The default helper files created in RSpec 3.x have changed
10-
```
11-
12-
In prior versions, only a single `spec_helper.rb` file was generated. This file
13-
has been moved to `rails_helper.rb`. The new `spec_helper.rb` is the same
14-
standard helper generated by running `rspec --init`.
15-
16-
This change was made to accomplish two general goals:
17-
18-
- Keep the installation process in sync with regular RSpec changes
19-
20-
- Provide an out-of-the-box way to avoid loading Rails for those specs that do
21-
not require it
22-
23-
## Upgrading an Existing App
24-
25-
For most existing apps, one of the following upgrade paths is sufficient to
26-
switch to the new helpers:
27-
28-
### I need to move things over in stages
29-
30-
1. Create a new `rails_helper.rb` with the following content:
31-
32-
```ruby
33-
require 'spec_helper'
34-
```
35-
36-
2. As necessary, replace `require 'spec_helper'` with `require 'rails_helper'`
37-
in the specs.
38-
39-
3. When ready, move any Rails specific code and setup from `spec_helper.rb` to
40-
`rails_helper.rb`.
41-
42-
### I'm ready to just switch completely
43-
44-
1. Move the existing `spec_helper.rb` to `rails_helper.rb`:
45-
46-
```ruby
47-
git mv spec/spec_helper.rb spec/rails_helper.rb
48-
```
49-
50-
2. Run the installation rake task opting to not replace `rails_helper.rb`:
51-
52-
```console
53-
$ bin/rails generate rspec:install
54-
create .rspec
55-
exist spec
56-
create spec/spec_helper.rb
57-
conflict spec/rails_helper.rb
58-
Overwrite my_app/spec/rails_helper.rb? (enter "h"for help) [Ynaqdh] n
59-
skip spec/rails_helper.rb
60-
```
61-
62-
3. Move any non-Rails RSpec configurations and customizations from your
63-
`rails_helper.rb` to `spec_helper.rb`.
64-
65-
4. Find/replace instances of `require 'spec_helper'` with
66-
`require 'rails_helper'` in any specs which rely on Rails.
67-
68-
## Generators
69-
70-
Generators run in RSpec 3.x will use the `rails_helper` by default.
71-
721
# Upgrading from rspec-rails-1.x to rspec-rails-2
732

743
This is a work in progress. Please submit errata, missing steps, or patches to

0 commit comments

Comments
 (0)