clearance 1.8.0 → 1.13.0

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of clearance might be problematic. Click here for more details.

Files changed (100) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +2 -0
  3. data/.travis.yml +24 -6
  4. data/.yardopts +6 -0
  5. data/Appraisals +12 -4
  6. data/CONTRIBUTING.md +4 -1
  7. data/Gemfile +2 -2
  8. data/Gemfile.lock +87 -85
  9. data/NEWS.md +672 -311
  10. data/README.md +185 -330
  11. data/app/controllers/clearance/passwords_controller.rb +25 -19
  12. data/app/controllers/clearance/sessions_controller.rb +17 -4
  13. data/app/controllers/clearance/users_controller.rb +10 -4
  14. data/app/mailers/clearance_mailer.rb +2 -3
  15. data/app/views/clearance_mailer/change_password.html.erb +6 -3
  16. data/app/views/clearance_mailer/change_password.text.erb +5 -0
  17. data/app/views/layouts/application.html.erb +2 -2
  18. data/app/views/passwords/create.html.erb +1 -1
  19. data/app/views/passwords/edit.html.erb +2 -2
  20. data/app/views/passwords/new.html.erb +2 -2
  21. data/app/views/sessions/_form.html.erb +2 -2
  22. data/app/views/sessions/new.html.erb +1 -1
  23. data/app/views/users/new.html.erb +2 -2
  24. data/bin/setup +6 -2
  25. data/config/locales/clearance.en.yml +6 -0
  26. data/db/migrate/20110111224543_create_clearance_users.rb +1 -1
  27. data/gemfiles/{rails3.2.gemfile → rails32.gemfile} +1 -1
  28. data/gemfiles/{rails4.0.gemfile → rails40.gemfile} +2 -2
  29. data/gemfiles/{rails4.1.gemfile → rails41.gemfile} +2 -2
  30. data/gemfiles/{rails4.2.gemfile → rails42.gemfile} +2 -2
  31. data/gemfiles/rails50.gemfile +19 -0
  32. data/lib/clearance/authentication.rb +52 -1
  33. data/lib/clearance/authorization.rb +47 -4
  34. data/lib/clearance/back_door.rb +1 -0
  35. data/lib/clearance/configuration.rb +127 -15
  36. data/lib/clearance/constraints/signed_in.rb +21 -0
  37. data/lib/clearance/constraints/signed_out.rb +12 -0
  38. data/lib/clearance/constraints.rb +12 -0
  39. data/lib/clearance/controller.rb +13 -0
  40. data/lib/clearance/default_sign_in_guard.rb +17 -0
  41. data/lib/clearance/engine.rb +24 -4
  42. data/lib/clearance/password_strategies/bcrypt.rb +9 -2
  43. data/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb +19 -0
  44. data/lib/clearance/password_strategies/blowfish.rb +17 -0
  45. data/lib/clearance/password_strategies/sha1.rb +17 -0
  46. data/lib/clearance/password_strategies.rb +13 -0
  47. data/lib/clearance/rack_session.rb +13 -0
  48. data/lib/clearance/rspec.rb +15 -4
  49. data/lib/clearance/session.rb +46 -1
  50. data/lib/clearance/session_status.rb +7 -0
  51. data/lib/clearance/sign_in_guard.rb +65 -0
  52. data/lib/clearance/test_unit.rb +3 -3
  53. data/lib/clearance/testing/controller_helpers.rb +44 -0
  54. data/lib/clearance/testing/deny_access_matcher.rb +35 -1
  55. data/lib/clearance/testing/helpers.rb +9 -25
  56. data/lib/clearance/testing/view_helpers.rb +32 -0
  57. data/lib/clearance/token.rb +7 -0
  58. data/lib/clearance/user.rb +159 -0
  59. data/lib/clearance/version.rb +1 -1
  60. data/lib/clearance.rb +2 -0
  61. data/lib/generators/clearance/install/install_generator.rb +13 -3
  62. data/lib/generators/clearance/install/templates/db/migrate/add_clearance_to_users.rb +3 -3
  63. data/lib/generators/clearance/install/templates/db/migrate/create_users.rb +2 -2
  64. data/lib/generators/clearance/routes/routes_generator.rb +23 -0
  65. data/lib/generators/clearance/routes/templates/routes.rb +7 -7
  66. data/lib/generators/clearance/specs/templates/features/clearance/user_signs_out_spec.rb.tt +1 -1
  67. data/lib/generators/clearance/specs/templates/features/clearance/visitor_resets_password_spec.rb.tt +12 -2
  68. data/lib/generators/clearance/specs/templates/features/clearance/visitor_signs_in_spec.rb.tt +1 -1
  69. data/lib/generators/clearance/specs/templates/features/clearance/visitor_signs_up_spec.rb.tt +1 -1
  70. data/lib/generators/clearance/specs/templates/features/clearance/visitor_updates_password_spec.rb.tt +1 -1
  71. data/spec/acceptance/clearance_installation_spec.rb +4 -1
  72. data/spec/app_templates/config/initializers/clearance.rb +2 -0
  73. data/spec/app_templates/testapp/app/controllers/home_controller.rb +5 -1
  74. data/spec/app_templates/testapp/config/initializers/action_mailer.rb +1 -3
  75. data/spec/clearance/controller_spec.rb +11 -0
  76. data/spec/clearance/rack_session_spec.rb +5 -5
  77. data/spec/clearance/testing/{helpers_spec.rb → controller_helpers_spec.rb} +12 -12
  78. data/spec/clearance/testing/view_helpers_spec.rb +37 -0
  79. data/spec/configuration_spec.rb +24 -0
  80. data/spec/controllers/apis_controller_spec.rb +6 -2
  81. data/spec/controllers/forgeries_controller_spec.rb +6 -1
  82. data/spec/controllers/passwords_controller_spec.rb +1 -11
  83. data/spec/controllers/permissions_controller_spec.rb +13 -3
  84. data/spec/controllers/sessions_controller_spec.rb +4 -4
  85. data/spec/dummy/app/controllers/application_controller.rb +5 -1
  86. data/spec/dummy/application.rb +4 -0
  87. data/spec/generators/clearance/install/install_generator_spec.rb +15 -3
  88. data/spec/generators/clearance/routes/routes_generator_spec.rb +5 -1
  89. data/spec/generators/clearance/views/views_generator_spec.rb +11 -10
  90. data/spec/helpers/helper_helpers_spec.rb +10 -0
  91. data/spec/mailers/clearance_mailer_spec.rb +13 -19
  92. data/spec/password_strategies/bcrypt_migration_from_sha1_spec.rb +6 -0
  93. data/spec/password_strategies/blowfish_spec.rb +6 -0
  94. data/spec/password_strategies/sha1_spec.rb +6 -0
  95. data/spec/spec_helper.rb +7 -0
  96. data/spec/support/generator_spec_helpers.rb +4 -0
  97. data/spec/support/http_method_shim.rb +23 -0
  98. data/spec/user_spec.rb +9 -0
  99. data/spec/views/view_helpers_spec.rb +10 -0
  100. metadata +19 -8
data/README.md CHANGED
@@ -1,14 +1,13 @@
1
- Clearance
2
- =========
1
+ # Clearance
3
2
 
4
3
  [![Build Status](https://secure.travis-ci.org/thoughtbot/clearance.svg)](http://travis-ci.org/thoughtbot/clearance?branch=master)
5
4
  [![Code Climate](https://codeclimate.com/github/thoughtbot/clearance.svg)](https://codeclimate.com/github/thoughtbot/clearance)
5
+ [![Documentation Quality](https://inch-ci.org/github/thoughtbot/clearance.svg?branch=master)](https://inch-ci.org/github/thoughtbot/clearance)
6
6
 
7
7
  Rails authentication with email & password.
8
8
 
9
- Clearance was extracted out of [Airbrake](http://airbrake.io/). It is intended
10
- to be small, simple, and well-tested. It is intended to be easy to override
11
- defaults.
9
+ Clearance is intended to be small, simple, and well-tested. It has opinionated
10
+ defaults but is intended to be easy to override.
12
11
 
13
12
  Please use [GitHub Issues] to report bugs. If you have a question about the
14
13
  library, please use the `clearance` tag on [Stack Overflow]. This tag is
@@ -17,45 +16,33 @@ monitored by contributors.
17
16
  [GitHub Issues]: https://github.com/thoughtbot/clearance/issues
18
17
  [Stack Overflow]: http://stackoverflow.com/questions/tagged/clearance
19
18
 
20
- Read [CONTRIBUTING.md](/CONTRIBUTING.md) to contribute.
21
-
22
- Install
23
- -------
19
+ ## Getting Started
24
20
 
25
21
  Clearance is a Rails engine tested against Rails `>= 3.2` and Ruby `>= 1.9.3`.
26
- It works with Rails 4 and Ruby 2.
27
22
 
28
- Include the gem in your Gemfile:
23
+ You can add it to your Gemfile with:
29
24
 
30
- ```ruby
25
+ ```sh
31
26
  gem 'clearance'
32
27
  ```
33
28
 
34
- Bundle:
35
-
36
- bundle install
37
-
38
- Make sure the development database exists. Then, run the generator:
39
-
40
- rails generate clearance:install
29
+ Run the bundle command to install it.
41
30
 
42
- The generator:
31
+ After you install Clearance, you need to run the generator:
43
32
 
44
- * inserts `Clearance::User` into your `User` model
45
- * inserts `Clearance::Controller` into your `ApplicationController`
46
- * creates a migration that either creates a users table or adds only missing
47
- columns
48
-
49
- Then, follow the instructions output from the generator.
33
+ ```sh
34
+ $ rails generate clearance:install
35
+ ```
50
36
 
51
- Use Clearance [0.8.8](https://github.com/thoughtbot/clearance/tree/v0.8.8) for
52
- Rails 2 apps.
37
+ The Clearance install generator:
53
38
 
54
- Use Clearance [0.16.3](http://rubygems.org/gems/clearance/versions/0.16.3) for
55
- Ruby 1.8.7 apps.
39
+ * Inserts `Clearance::User` into your `User` model
40
+ * Inserts `Clearance::Controller` into your `ApplicationController`
41
+ * Creates an initializer file to allow further configuration.
42
+ * Creates a migration file that either create a users table or adds any necessary
43
+ columns to the existing table.
56
44
 
57
- Configure
58
- ---------
45
+ ## Configure
59
46
 
60
47
  Override any of these defaults in `config/initializers/clearance.rb`:
61
48
 
@@ -77,40 +64,15 @@ Clearance.configure do |config|
77
64
  end
78
65
  ```
79
66
 
80
- Use
81
- ---
67
+ ## Use
82
68
 
83
- Use `current_user`, `signed_in?`, and `signed_out?` in controllers, views, and
84
- helpers. For example:
69
+ ### Access Control
85
70
 
86
- ```haml
87
- - if signed_in?
88
- = current_user.email
89
- = button_to 'Sign out', sign_out_path, method: :delete
90
- - else
91
- = link_to 'Sign in', sign_in_path
92
- ```
93
-
94
- To authenticate a user elsewhere than `sessions/new` (like in an API):
95
-
96
- ```ruby
97
- User.authenticate 'email@example.com', 'password'
98
- ```
99
-
100
- When a user resets their password, Clearance delivers them an email. So, you
101
- should change the `mailer_sender` default, used in the email's "from" header:
102
-
103
- ```ruby
104
- Clearance.configure do |config|
105
- config.mailer_sender = 'reply@example.com'
106
- end
107
- ```
108
-
109
- Use `require_login` to control access in controllers:
71
+ Use the `require_login` filter to control access to controller actions.
110
72
 
111
73
  ```ruby
112
74
  class ArticlesController < ApplicationController
113
- before_filter :require_login
75
+ before_action :require_login
114
76
 
115
77
  def index
116
78
  current_user.articles
@@ -118,7 +80,8 @@ class ArticlesController < ApplicationController
118
80
  end
119
81
  ```
120
82
 
121
- Or, you can authorize users in `config/routes.rb`:
83
+ Clearance also provides routing constraints that can be used to control access
84
+ at the routing layer:
122
85
 
123
86
  ```ruby
124
87
  Blog::Application.routes.draw do
@@ -136,6 +99,33 @@ Blog::Application.routes.draw do
136
99
  end
137
100
  ```
138
101
 
102
+ ### Helper Methods
103
+
104
+ Use `current_user`, `signed_in?`, and `signed_out?` in controllers, views, and
105
+ helpers. For example:
106
+
107
+ ```erb
108
+ <% if signed_in? %>
109
+ <%= current_user.email %>
110
+ <%= button_to "Sign out", sign_out_path, method: :delete %>
111
+ <% else %>
112
+ <%= link_to "Sign in", sign_in_path %>
113
+ <% end %>
114
+ ```
115
+
116
+ ### Password Resets
117
+
118
+ When a user resets their password, Clearance delivers them an email. You
119
+ should change the `mailer_sender` default, used in the email's "from" header:
120
+
121
+ ```ruby
122
+ Clearance.configure do |config|
123
+ config.mailer_sender = 'reply@example.com'
124
+ end
125
+ ```
126
+
127
+ ### Integrating with Rack Applications
128
+
139
129
  Clearance adds its session to the Rack environment hash so middleware and other
140
130
  Rack applications can interact with it:
141
131
 
@@ -155,28 +145,27 @@ class Bubblegum::Middleware
155
145
  end
156
146
  ```
157
147
 
158
- Overriding routes
159
- -----------------
148
+ ## Overriding Clearance
149
+
150
+ ### Routes
160
151
 
161
152
  See [config/routes.rb](/config/routes.rb) for the default set of routes.
162
153
 
163
- Route overrides became more difficult with [changes made in Rails
164
- 4][rails_routes]. For this reason, Clearance 1.5 introduces an option to disable
165
- all clearance routes, giving the user full control over routing and URL design.
154
+ As of Clearance 1.5 it is recommended that you disable Clearance routes and take
155
+ full control over routing and URL design.
166
156
 
167
157
  To disable the routes, set `config.routes = false`. You can optionally run
168
158
  `rails generate clearance:routes` to dump a copy of the default routes into your
169
159
  application for modification.
170
160
 
171
- [rails_routes]: https://github.com/rails/rails/issues/11895
172
-
173
- Overriding controllers
174
- ----------------------
161
+ ### Controllers
175
162
 
176
163
  See [app/controllers/clearance](/app/controllers/clearance) for the default
177
- behavior.
164
+ behavior. Many protected methods were extracted in these controllers in an
165
+ attempt to make overrides and hooks simpler.
178
166
 
179
- To override a Clearance controller, subclass it:
167
+ To override a Clearance controller, subclass it and update the routes to
168
+ point to your new controller (see the "Routes" section).
180
169
 
181
170
  ```ruby
182
171
  class PasswordsController < Clearance::PasswordsController
@@ -184,203 +173,84 @@ class SessionsController < Clearance::SessionsController
184
173
  class UsersController < Clearance::UsersController
185
174
  ```
186
175
 
187
- Don't forget to [override routes](#overriding-routes) to your new controllers!
188
-
189
- Then, override public methods:
190
-
191
- passwords#create
192
- passwords#edit
193
- passwords#new
194
- passwords#update
195
- sessions#create
196
- sessions#destroy
197
- sessions#new
198
- users#create
199
- users#new
200
-
201
- Or, override private methods:
202
-
203
- passwords#find_user_by_id_and_confirmation_token
204
- passwords#find_user_for_create
205
- passwords#find_user_for_edit
206
- passwords#find_user_for_update
207
- passwords#flash_failure_after_create
208
- passwords#flash_failure_after_update
209
- passwords#flash_failure_when_forbidden
210
- passwords#forbid_missing_token
211
- passwords#forbid_non_existent_user
212
- passwords#url_after_create
213
- passwords#url_after_update
214
- sessions#url_after_create
215
- sessions#url_after_destroy
216
- users#flash_failure_after_create
217
- users#url_after_create
218
- users#user_from_params
219
- users#user_params
220
-
221
- All of these controller methods redirect to `'/'` by default:
222
-
223
- passwords#url_after_update
224
- sessions#url_after_create
225
- sessions#url_for_signed_in_users
226
- users#url_after_create
227
- application#url_after_denied_access_when_signed_in
228
-
229
- To override them all at once, change the global configuration:
230
-
231
- ```ruby
232
- Clearance.configure do |config|
233
- config.redirect_url = '/overridden'
234
- end
235
- ```
236
-
237
- Overriding translations
238
- -----------------------
239
-
240
- All flash messages and email subject lines are stored in
241
- [i18n translations](http://guides.rubyonrails.org/i18n.html).
242
- Override them like any other translation.
243
-
244
- See [config/locales/clearance.en.yml](/config/locales/clearance.en.yml) for the
245
- default behavior.
176
+ ### Redirects
246
177
 
247
- Overriding layouts
248
- ----------------
178
+ All of these controller methods redirect to
179
+ `Clearance.configuration.redirect_url` (which is `/` by default):
249
180
 
250
- By default, Clearance uses your application's default layout. If you would like
251
- to change the layout that Clearance uses when rendering its views, simply specify
252
- the layout in an initializer.
253
-
254
- ```ruby
255
- Clearance::PasswordsController.layout 'my_passwords_layout'
256
- Clearance::SessionsController.layout 'my_sessions_layout'
257
- Clearance::UsersController.layout 'my_admin_layout'
181
+ ```
182
+ passwords#url_after_update
183
+ sessions#url_after_create
184
+ sessions#url_for_signed_in_users
185
+ users#url_after_create
186
+ application#url_after_denied_access_when_signed_in
258
187
  ```
259
188
 
260
- Overriding views
261
- ----------------
262
-
263
- See [app/views](/app/views) for the default behavior.
264
-
265
- To override a view, create your own:
266
-
267
- app/views/clearance_mailer/change_password.html.erb
268
- app/views/passwords/create.html.erb
269
- app/views/passwords/edit.html.erb
270
- app/views/passwords/new.html.erb
271
- app/views/sessions/_form.html.erb
272
- app/views/sessions/new.html.erb
273
- app/views/users/_form.html.erb
274
- app/views/users/new.html.erb
275
-
276
- There is a shortcut to copy all Clearance views into your app:
277
-
278
- rails generate clearance:views
279
-
280
- Overriding the model
281
- --------------------
282
-
283
- See [lib/clearance/user.rb](/lib/clearance/user.rb) for the default behavior.
284
-
285
- To override the model, redefine public methods:
286
-
287
- User.authenticate(email, password)
288
- User#forgot_password!
289
- User#reset_remember_token!
290
- User#update_password(new_password)
291
-
292
- Or, redefine private methods:
293
-
294
- User#email_optional?
295
- User#generate_confirmation_token
296
- User#generate_remember_token
297
- User#normalize_email
298
- User#password_optional?
189
+ To override them all at once, change the global configuration of `redirect_url`.
190
+ To change individual URLs, override the appropriate method.
299
191
 
300
- Overriding the password strategy
301
- --------------------------------
192
+ `application#url_after_denied_access_when_signed_out` defaults to `sign_in_url`.
193
+ Override this method to change this.
302
194
 
303
- By default, Clearance uses BCrypt encryption of the user's password.
195
+ ### Views
304
196
 
305
- See
306
- [lib/clearance/password_strategies/bcrypt.rb](/lib/clearance/password_strategies/bcrypt.rb)
307
- for the default behavior.
197
+ See [app/views](/app/views) for the default behavior.
308
198
 
309
- Change your password strategy in `config/initializers/clearance.rb:`
199
+ To override a view, create your own copy of it:
310
200
 
311
- ```ruby
312
- Clearance.configure do |config|
313
- config.password_strategy = Clearance::PasswordStrategies::SHA1
314
- end
315
201
  ```
316
-
317
- Clearance provides the following strategies:
318
-
319
- ```ruby
320
- Clearance::PasswordStrategies::BCrypt
321
- Clearance::PasswordStrategies::BCryptMigrationFromSHA1
322
- Clearance::PasswordStrategies::Blowfish
323
- Clearance::PasswordStrategies::SHA1
202
+ app/views/clearance_mailer/change_password.html.erb
203
+ app/views/passwords/create.html.erb
204
+ app/views/passwords/edit.html.erb
205
+ app/views/passwords/new.html.erb
206
+ app/views/sessions/_form.html.erb
207
+ app/views/sessions/new.html.erb
208
+ app/views/users/_form.html.erb
209
+ app/views/users/new.html.erb
324
210
  ```
325
211
 
326
- The previous default password strategy was SHA1.
327
-
328
- Switching password strategies may cause your existing users to not be able to sign in.
212
+ You can use the Clearance views generator to copy the default views to your
213
+ application for modification.
329
214
 
330
- If you have an existing app that used the old `SHA1` strategy and you want to
331
- stay with SHA1, use
332
- [Clearance::PasswordStrategies::SHA1](/lib/clearance/password_strategies/sha1.rb).
215
+ ```shell
216
+ $ rails generate clearance:views
217
+ ```
333
218
 
334
- If you have an existing app that used the old `SHA1` strategy and you want to
335
- switch to BCrypt transparently, use
336
- [Clearance::PasswordStrategies::BCryptMigrationFromSHA1](/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb).
219
+ ### Layouts
337
220
 
338
- The SHA1 and Blowfish password strategies require an additional `salt` column in
339
- the `users` table. Run this migration before switching to SHA or Blowfish:
221
+ By default, Clearance uses your application's default layout. If you would like
222
+ to change the layout that Clearance uses when rendering its views, simply
223
+ specify the layout in an initializer.
340
224
 
341
225
  ```ruby
342
- class AddSaltToUsers < ActiveRecord::Migration
343
- def change
344
- add_column :users, :salt, :string, limit: 128
345
- end
346
- end
226
+ Clearance::PasswordsController.layout 'my_passwords_layout'
227
+ Clearance::SessionsController.layout 'my_sessions_layout'
228
+ Clearance::UsersController.layout 'my_admin_layout'
347
229
  ```
348
230
 
349
- You can write a custom password strategy that has two instance methods.
350
- In your `authenticated?` method, encrypt the password with your desired
351
- strategy, and then compare it to the `encrypted_password` that is provided by
352
- Clearance.
231
+ ### Translations
353
232
 
354
- ```ruby
355
- module CustomPasswordStrategy
356
- def authenticated?(password)
357
- encrypted_password == encrypt(password)
358
- end
359
-
360
- def password=(new_password)
361
- end
233
+ All flash messages and email subject lines are stored in [i18n translations]
234
+ (http://guides.rubyonrails.org/i18n.html). Override them like any other
235
+ translation.
362
236
 
363
- private
237
+ See [config/locales/clearance.en.yml](/config/locales/clearance.en.yml) for the
238
+ default behavior.
364
239
 
365
- def encrypt
366
- # your encryption strategy
367
- end
368
- end
240
+ ### User Model
369
241
 
370
- Clearance.configure do |config|
371
- config.password_strategy = CustomPasswordStrategy
372
- end
373
- ```
242
+ See [lib/clearance/user.rb](/lib/clearance/user.rb) for the default behavior.
243
+ You can override those methods as needed.
374
244
 
375
- Deliver password reset email in a background job
376
- ------------------------------------------------
245
+ ### Deliver Email in Background Job
377
246
 
378
- Clearance has one mailer. It is used to reset the user's password.
247
+ Clearance has a password reset mailer. If you are using Rails 4.2 and Clearance
248
+ 1.6 or greater, Clearance will use ActiveJob's `deliver_later` method to
249
+ automatically take advantage of your configured queue.
379
250
 
380
- To deliver it in a background job using a queue system like [Delayed
381
- Job](https://github.com/collectiveidea/delayed_job), subclass
382
- `Clearance::PasswordsController` and define the behavior you need in its
383
- `deliver_email` method:
251
+ If you are using an earlier version of Rails, you can override the
252
+ `Clearance::Passwords` controller and define the behavior you need in the
253
+ `deliver_email` method.
384
254
 
385
255
  ```ruby
386
256
  class PasswordsController < Clearance::PasswordsController
@@ -390,14 +260,13 @@ class PasswordsController < Clearance::PasswordsController
390
260
  end
391
261
  ```
392
262
 
393
- Then, override the route:
394
-
395
- ```ruby
396
- resources :passwords, only: [:create]
397
- ```
263
+ ## Extending Sign In
398
264
 
399
- Using the SignInGuard stack
400
- -------------------
265
+ By default, Clearance will sign in any user with valid credentials. If you need
266
+ to support additional checks during the sign in process then you can use the
267
+ SignInGuard stack. For example, using the SignInGuard stack, you could prevent
268
+ suspended users from signing in, or require that users confirm their email
269
+ address before accessing the site.
401
270
 
402
271
  `SignInGuard`s offer fine-grained control over the process of
403
272
  signing in a user. Each guard is run in order and hands the session off to
@@ -441,39 +310,52 @@ class EmailConfirmationGuard < Clearance::SignInGuard
441
310
  end
442
311
  ```
443
312
 
444
- Optional feature specs
445
- ----------------------
313
+ ## Testing
314
+
315
+ ### Fast Feature Specs
316
+
317
+ Clearance includes middleware that avoids wasting time spent visiting, loading,
318
+ and submitting the sign in form. It instead signs in the designated user
319
+ directly. The speed increase can be [substantial][backdoor].
446
320
 
447
- You can generate feature specs to help prevent regressions in Clearance's
448
- integration with your Rails app over time.
321
+ [backdoor]: http://robots.thoughtbot.com/post/37907699673/faster-tests-sign-in-through-the-back-door
449
322
 
450
- Edit your `Gemfile` to include the dependencies:
323
+ Enable the Middleware in Test:
451
324
 
452
325
  ```ruby
453
- gem 'capybara', '~> 2.0'
454
- gem 'factory_girl_rails', '~> 4.2'
455
- gem 'rspec-rails', '~> 2.13'
326
+ # config/environments/test.rb
327
+ MyRailsApp::Application.configure do
328
+ # ...
329
+ config.middleware.use Clearance::BackDoor
330
+ # ...
331
+ end
456
332
  ```
457
333
 
458
- Generate RSpec files:
334
+ Usage:
459
335
 
460
- rails generate rspec:install
336
+ ```ruby
337
+ visit root_path(as: user)
338
+ ```
461
339
 
462
- Generate Clearance specs:
340
+ ### Ready Made Feature Specs
463
341
 
464
- rails generate clearance:specs
342
+ If you're using RSpec, you can generate feature specs to help prevent
343
+ regressions in Clearance's integration with your Rails app over time. These
344
+ feature specs, will also require `factory_girl_rails`.
465
345
 
466
- Run the specs:
346
+ To Generate the clearance specs, run:
467
347
 
468
- rake
348
+ ```shell
349
+ $ rails generate clearance:specs
350
+ ```
469
351
 
470
- Testing controller actions that require login
471
- ---------------------------------------------
352
+ ### Controller Test Helpers
472
353
 
473
- To test controller actions that are protected by `before_filter :require_login`,
474
- require Clearance's test helpers and matchers in your test suite.
354
+ To test controller actions that are protected by `before_action :require_login`,
355
+ require Clearance's test helpers in your test suite.
475
356
 
476
- For `rspec`, add this line to your `spec/spec_helper.rb`:
357
+ For `rspec`, add the following line to your `spec/rails_helper.rb` or
358
+ `spec/spec_helper` if `rails_helper` does not exist:
477
359
 
478
360
  ```ruby
479
361
  require 'clearance/rspec'
@@ -488,81 +370,54 @@ require 'clearance/test_unit'
488
370
  This will make `Clearance::Controller` methods work in your controllers
489
371
  during functional tests and provide access to helper methods like:
490
372
 
491
- sign_in
492
- sign_in_as(user)
493
- sign_out
494
-
495
- And matchers like:
496
-
497
- deny_access
498
-
499
- Example:
500
-
501
373
  ```ruby
502
- context 'a guest' do
503
- before do
504
- get :show
505
- end
506
-
507
- it { should deny_access }
508
- end
509
-
510
- context 'a user' do
511
- before do
512
- sign_in
513
- get :show
514
- end
515
-
516
- it { should respond_with(:success) }
517
- end
374
+ sign_in
375
+ sign_in_as(user)
376
+ sign_out
518
377
  ```
519
378
 
520
- You may want to customize the tests:
379
+ ### View and Helper Spec Helpers
380
+
381
+ Does the view or helper you're testing reference `signed_in?`, `signed_out?` or
382
+ `current_user`? If you `require 'clearance/rspec'`, you will have the following
383
+ helpers available in your view specs:
521
384
 
522
385
  ```ruby
523
- it { should deny_access }
524
- it { should deny_access(flash: 'Denied access.') }
525
- it { should deny_access(redirect: sign_in_url) }
386
+ sign_in
387
+ sign_in_as(user)
526
388
  ```
527
389
 
528
- Faster tests
529
- ------------
390
+ These will make the clearance view helpers work as expected by signing in either
391
+ a new instance of your user model (`sign_in`) or the object you pass to
392
+ `sign_in_as`. If you do not call one of these sign in helpers or otherwise set
393
+ `current_user` in your view specs, your view will behave as if there is no
394
+ current user: `signed_in?` will be false and `signed_out?` will be true.
530
395
 
531
- Clearance includes middleware that avoids wasting time spent visiting, loading,
532
- and submitting the sign in form. It instead signs in the designated
533
- user directly. The speed increase can be
534
- [substantial](http://robots.thoughtbot.com/post/37907699673/faster-tests-sign-in-through-the-back-door).
396
+ ## Contributing
535
397
 
536
- Configuration:
398
+ Please see [CONTRIBUTING.md].
399
+ Thank you, [contributors]!
537
400
 
538
- ```ruby
539
- # config/environments/test.rb
540
- MyRailsApp::Application.configure do
541
- # ...
542
- config.middleware.use Clearance::BackDoor
543
- # ...
544
- end
545
- ```
401
+ [CONTRIBUTING.md]: /CONTRIBUTING.md
402
+ [contributors]: https://github.com/thoughtbot/clearance/graphs/contributors
546
403
 
547
- Usage:
404
+ ## License
548
405
 
549
- ```ruby
550
- visit root_path(as: user)
551
- ```
406
+ Clearance is copyright © 2009 thoughtbot. It is free software, and may be
407
+ redistributed under the terms specified in the [`LICENSE`] file.
552
408
 
553
- Credits
554
- -------
409
+ [`LICENSE`]: /LICENSE
555
410
 
556
- ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
411
+ ## About thoughtbot
557
412
 
558
- Clearance is maintained by [thoughtbot, inc](http://thoughtbot.com/community)
559
- and [contributors](https://github.com/thoughtbot/clearance/contributors) like
560
- you. Thank you!
413
+ ![thoughtbot](https://thoughtbot.com/logo.png)
561
414
 
562
- License
563
- -------
415
+ Clearance is maintained and funded by thoughtbot, inc.
416
+ The names and logos for thoughtbot are trademarks of thoughtbot, inc.
564
417
 
565
- Clearance is copyright © 2009 thoughtbot. It is free software, and may be
566
- redistributed under the terms specified in the `LICENSE` file.
418
+ We love open source software!
419
+ See [our other projects][community] or
420
+ [hire us][hire] to design, develop, and grow your product.
567
421
 
568
- The names and logos for thoughtbot are trademarks of thoughtbot, inc.
422
+ [community]: https://thoughtbot.com/community?utm_source=github
423
+ [hire]: https://thoughtbot.com/hire-us?utm_source=github