README.md in rspec-request_describer-0.2.2 vs README.md in rspec-request_describer-0.3.0
- old
+ new
@@ -1,88 +1,115 @@
# RSpec::RequestDescriber
-Force some rules to write self-documenting request spec.
+[](https://circleci.com/gh/r7kamura/rspec-request_describer)
+[](https://rubygems.org/gems/rspec-request_describer)
+
+An RSpec plugin to write self-documenting request-specs.
+
+This gem is designed for:
+
+- [rack-test](https://github.com/rack-test/rack-test)
+- [rspec-rails](https://github.com/rspec/rspec-rails)
+
## Setup
-Add `rspec-request_describer` into your Gemfile, then run `bundle install`.
+### Install
+
+Add this line to your application's Gemfile:
+
```ruby
-# Gemfile
-gem "rspec-request_describer"
+gem 'rspec-request_describer'
+```
-# rspec-request_describer depends on some methods of rspec-rails (or rack-test),
-# so you may need to add it unless you haven't do it yet.
-gem "rspec-rails" # or "rack-test"
+And then execute:
+
```
+bundle
+```
-Then include `RSpec::RequestDescriber` into your `RSpec.configuration`.
+Or install it yourself as:
+```
+gem install rspec-request_describer
+```
+
+### Include
+
+Include `RSpec::RequestDescriber` to your example groups like this:
+
```ruby
-# spec/spec_helper.rb
+require 'rspec/request_describer'
+
RSpec.configuration.include RSpec::RequestDescriber, type: :request
```
## Usage
-RSpec::RequestDescriber provides some `subject` and `let` to your specs.
### subject
-In the example below, the `subject` calls an HTTP request of GET /users,
-then returns its status code.
+`RSpec::RequestDescriber` provides `subject` from its top-level description.
+
```ruby
-describe "GET /users" do
- it { should == 200 }
+# subject will be `get('/users')`.
+RSpec.describe 'GET /users' do
+ it { is_expected.to eq(200) }
end
```
### headers
-`headers` is provided to modify request headers.
-In the below example, a token is added into Authorization request header.
+If you want to modify request headers, change `headers` before calling `subject`.
```ruby
-describe "GET /users" do
- context "with Authorization header" do
+# `subject` will be `get('/users', headers: { 'Authorization' => 'token 12345' })`.
+RSpec.describe 'GET /users' do
+ context 'with Authorization header' do
before do
- headers["Authorization"] = "token 12345"
+ headers['Authorization'] = 'token 12345'
end
- it { should == 200 }
+ it { is_expected.to eq(200) }
end
end
```
### params
-You can also pass query parameter or request body by modifying `params`.
-In the this example, `?sort=id` is added into URL query string.
-For GET request `params` is converted into URL query string,
-while it's converted into request body for the other methods
-.
-Note that if you specified `application/json` Content-Type request header,
-`params` would be encoded into JSON format.
+If you want to modify request parameters, change `params` before calling `subject`.
+
```ruby
-describe "GET /users" do
- context "with sort parameter" do
+# `subject` will be `get('/users', params: { 'sort' => 'id' })`.
+RSpec.describe 'GET /users' do
+ context 'with sort parameter' do
before do
- params["sort"] = "id"
+ params['sort'] = 'id'
end
- it "returns users in ID order" do
+ it 'returns users in ID order' do
+ is_expected.to eq(200)
+
users = JSON.parse(response.body)
- users[0].id.should == 1
- users[1].id.should == 2
+ expect(users[0]['id']).to eq(1)
+ expect(users[1]['id']).to eq(2)
end
end
end
```
-### variable
-You can use variables in URL path like `:id`.
-In this example, the returned value of `id` method is used as its real value.
+### variables in URL path
+You can embed variables in URL path like `/users/:id`.
+In this example, the returned value of `id` method will be emobeded as its real value.
+
```ruby
-describe "GET /users/:id" do
- let(:id) do
- User.create(name: "alice").id
+# `subject` will be `get("/users/#{user_id}")`.
+RSpec.describe 'GET /users/:user_id' do
+ let(:user) do
+ User.create(name: 'alice')
end
- it { should == 200 }
+
+ let(:user_id) do
+ user.id
+ end
+
+ it { is_expected.to eq(200) }
end
```