Skip to content
This repository
Browse code

Update README

  • Loading branch information...
commit da68e67bdab0b4dc3680ca475ae6ce6c55a0d3e1 1 parent bb03c89
Steve Richert authored February 24, 2012

Showing 1 changed file with 221 additions and 210 deletions. Show diff stats Hide diff stats

  1. 431  README.md
431  README.md
Source Rendered
... ...
@@ -1,24 +1,11 @@
1 1
 json_spec [![Build Status](https://secure.travis-ci.org/collectiveidea/json_spec.png)](http://travis-ci.org/collectiveidea/json_spec) [![Dependency Status](https://gemnasium.com/collectiveidea/json_spec.png)](https://gemnasium.com/collectiveidea/json_spec)
2  
-========
  2
+=========
3 3
 
4 4
 Easily handle JSON in RSpec and Cucumber
5 5
 
6  
-Installation
7  
-------------
8  
-    gem install json_spec
9  
-
10  
-or with Bundler:
11  
-
12  
-    gem "json_spec"
13  
-
14  
-Documentation
15  
--------------
16  
-Please help write documentation!
17  
-
18  
-[http://rdoc.info/gems/json_spec](http://rdoc.info/gems/json_spec)
19  
-
20 6
 RSpec
21 7
 --------------
  8
+
22 9
 json_spec defines five new RSpec matchers:
23 10
 
24 11
 * `be_json_eql`
@@ -29,43 +16,50 @@ json_spec defines five new RSpec matchers:
29 16
 
30 17
 The new matchers could be used in RSpec as follows:
31 18
 
32  
-    describe User do
33  
-      let(:user){ User.create!(:first_name => "Steve", :last_name => "Richert") }
  19
+```ruby
  20
+describe User do
  21
+  let(:user){ User.create!(first_name: "Steve", last_name: "Richert") }
  22
+
  23
+  context "#to_json" do
  24
+    it "includes names" do
  25
+      names = %({"first_name":"Steve","last_name":"Richert"})
  26
+      user.to_json.should be_json_eql(names).excluding("friends")
  27
+    end
34 28
 
35  
-      context "#to_json" do
36  
-        let(:json){ user.to_json }
  29
+    it "includes the ID" do
  30
+      user.to_json.should have_json_path("id")
  31
+      user.to_json.should have_json_type(Integer).at_path("id")
  32
+    end
37 33
 
38  
-        it "includes the name" do
39  
-          json.should be_json_eql(%({"first_name":"Steve","last_name":"Richert"})).excluding("friends")
40  
-        end
  34
+    it "includes friends" do
  35
+      user.to_json.should have_json_size(0).at_path("friends")
41 36
 
42  
-        it "includes the ID" do
43  
-          json.should have_json_path("id")
44  
-          json.should have_json_type(Integer).at_path("id")
45  
-        end
  37
+      friend = User.create!(first_name: "Catie", last_name: "Richert")
  38
+      user.friends << friend
46 39
 
47  
-        it "includes friends" do
48  
-          json.should have_json_size(0).at_path("friends")
49  
-          user.friends << User.create!(:first_name => "Catie", :last_name => "Richert")
50  
-          json.should have_json_size(1).at_path("friends")
51  
-          json.should include_json(%({"first_name":"Catie","last_name":"Richert"}))
52  
-        end
53  
-      end
  40
+      user.to_json.should have_json_size(1).at_path("friends")
  41
+      user.to_json.should include_json(friend.to_json)
54 42
     end
  43
+  end
  44
+end
  45
+```
55 46
 
56  
-Also json_spec provides some useful helpers for RSpec tests:
  47
+json_spec also provides some useful helpers for RSpec tests:
57 48
 
58 49
 * `parse_json`
59 50
 * `normalize_json`
60 51
 * `generate_normalized_json`
  52
+* `load_json`
61 53
 
62  
-To start using them add include statement in your Rspec.configure at spec_helper.rb file:
  54
+To start using them add an include them in your RSpec configuration:
63 55
 
64  
-    RSpec.configure do |config|
65  
-      config.include JsonSpec::Helpers
66  
-    end
  56
+```ruby
  57
+RSpec.configure do |config|
  58
+  config.include JsonSpec::Helpers
  59
+end
  60
+```
67 61
 
68  
-Examples of usage this methods you can find in spec/json_spec/helpers_spec.rb
  62
+You can find usage examples for the helpers in [`spec/json_spec/helpers_spec.rb`](https://github.com/collectiveidea/json_spec/blob/master/spec/json_spec/helpers_spec.rb)
69 63
 
70 64
 ### Exclusions
71 65
 
@@ -79,13 +73,15 @@ It's oftentimes helpful when evaluating JSON representations of newly-created Ac
79 73
 so that the new ID and timestamps don't have to be known. These exclusions are globally
80 74
 customizeable:
81 75
 
82  
-    JsonSpec.configure do
83  
-      exclude_keys "created_at", "updated_at"
84  
-    end
  76
+```ruby
  77
+JsonSpec.configure do
  78
+  exclude_keys "created_at", "updated_at"
  79
+end
  80
+```
85 81
 
86 82
 Now, the `id` key will be included in json_spec's comparisons. Keys can also be excluded/included
87  
-per matcher by chaining the `excluding` or `including` methods (as shown above) which will add or subtract from
88  
-the globally excluded keys, respectively.
  83
+per matcher by chaining the `excluding` or `including` methods (as shown above) which will add or
  84
+subtract from the globally excluded keys, respectively.
89 85
 
90 86
 ### Paths
91 87
 
@@ -107,151 +103,168 @@ We could access the first friend's first name with the path `"friends/0/first_na
107 103
 
108 104
 Cucumber
109 105
 --------
  106
+
110 107
 json_spec provides Cucumber steps that utilize its RSpec matchers and that's where json_spec really
111 108
 shines. This is perfect for testing your app's JSON API.
112 109
 
113 110
 In order to use the Cucumber steps, in your `env.rb` you must:
114 111
 
115  
-    require "json_spec/cucumber"
  112
+```ruby
  113
+require "json_spec/cucumber"
  114
+```
116 115
 
117 116
 You also need to define a `last_json` method. If you're using Capybara, it could be as simple as:
118 117
 
119  
-    def last_json
120  
-      page.source
121  
-    end
  118
+```ruby
  119
+def last_json
  120
+  page.source
  121
+end
  122
+```
122 123
 
123 124
 Now, you can use the json_spec steps in your features:
124 125
 
125  
-    Feature: User API
126  
-      Background:
127  
-        Given the following users exist:
128  
-          | id | first_name | last_name |
129  
-          | 1  | Steve      | Richert   |
130  
-          | 2  | Catie      | Richert   |
131  
-        And "Steve Richert" is friends with "Catie Richert"
132  
-
133  
-      Scenario: Index action
134  
-        When I visit "/users.json"
135  
-        Then the JSON response should have 2 users
136  
-        And the JSON response at "0/id" should be 1
137  
-        And the JSON response at "1/id" should be 2
138  
-
139  
-      Scenario: Show action
140  
-        When I visit "/users/1.json"
141  
-        Then the JSON response at "first_name" should be "Steve"
142  
-        And the JSON response at "last_name" should be "Richert"
143  
-        And the JSON response should have "created_at"
144  
-        And the JSON response at "created_at" should be a string
145  
-        And the JSON response at "friends" should be:
146  
-          """
147  
-          [
148  
-            {
149  
-              "id": 2,
150  
-              "first_name": "Catie",
151  
-              "last_name": "Richert"
152  
-            }
153  
-          ]
154  
-          """
155  
-
156  
-The background steps above aren't provided by json_spec and the "visit" steps are provided by
157  
-Capybara. The remaining steps, json_spec provides. They're versatile and can be used in plenty of
158  
-different formats:
159  
-
160  
-    Then the JSON should be:
161  
-      """
162  
-      {
163  
-        "key": "value"
164  
-      }
165  
-      """
166  
-    Then the JSON at "path" should be:
  126
+```cucumber
  127
+Feature: User API
  128
+  Background:
  129
+    Given the following users exist:
  130
+      | id | first_name | last_name |
  131
+      | 1  | Steve      | Richert   |
  132
+      | 2  | Catie      | Richert   |
  133
+    And "Steve Richert" is friends with "Catie Richert"
  134
+
  135
+  Scenario: Index action
  136
+    When I visit "/users.json"
  137
+    Then the JSON response should have 2 users
  138
+    And the JSON response at "0/id" should be 1
  139
+    And the JSON response at "1/id" should be 2
  140
+
  141
+  Scenario: Show action
  142
+    When I visit "/users/1.json"
  143
+    Then the JSON response at "first_name" should be "Steve"
  144
+    And the JSON response at "last_name" should be "Richert"
  145
+    And the JSON response should have "created_at"
  146
+    And the JSON response at "created_at" should be a string
  147
+    And the JSON response at "friends" should be:
167 148
       """
168 149
       [
169  
-        "entry",
170  
-        "entry"
  150
+        {
  151
+          "id": 2,
  152
+          "first_name": "Catie",
  153
+          "last_name": "Richert"
  154
+        }
171 155
       ]
172 156
       """
  157
+```
173 158
 
174  
-    Then the JSON should be {"key":"value"}
175  
-    Then the JSON at "path" should be {"key":"value"}
176  
-    Then the JSON should be ["entry","entry"]
177  
-    Then the JSON at "path" should be ["entry","entry"]
178  
-    Then the JSON at "path" should be "string"
179  
-    Then the JSON at "path" should be 10
180  
-    Then the JSON at "path" should be 10.0
181  
-    Then the JSON at "path" should be 1e+1
182  
-    Then the JSON at "path" should be true
183  
-    Then the JSON at "path" should be false
184  
-    Then the JSON at "path" should be null
185  
-
186  
-    Then the JSON should include:
187  
-      """
188  
-      {
189  
-        "key": "value"
190  
-      }
191  
-      """
192  
-    Then the JSON at "path" should include:
193  
-      """
194  
-      [
195  
-        "entry",
196  
-        "entry"
197  
-      ]
198  
-      """
  159
+The background steps above aren't provided by json_spec and the "visit" steps are provided by
  160
+Capybara. The remaining steps, json_spec provides. They're versatile and can be used in plenty of
  161
+different formats:
199 162
 
200  
-    Then the JSON should include {"key":"value"}
201  
-    Then the JSON at "path" should include {"key":"value"}
202  
-    Then the JSON should include ["entry","entry"]
203  
-    Then the JSON at "path" should include ["entry","entry"]
204  
-    Then the JSON should include "string"
205  
-    Then the JSON at "path" should include "string"
206  
-    Then the JSON should include 10
207  
-    Then the JSON at "path" should include 10
208  
-    Then the JSON should include 10.0
209  
-    Then the JSON at "path" should include 10.0
210  
-    Then the JSON should include 1e+1
211  
-    Then the JSON at "path" should include 1e+1
212  
-    Then the JSON should include true
213  
-    Then the JSON at "path" should include true
214  
-    Then the JSON should include false
215  
-    Then the JSON at "path" should include false
216  
-    Then the JSON should include null
217  
-    Then the JSON at "path" should include null
218  
-
219  
-    Then the JSON should have "path"
220  
-
221  
-    Then the JSON should be a hash
222  
-    Then the JSON at "path" should be an array
223  
-    Then the JSON at "path" should be a float
224  
-
225  
-    Then the JSON should have 1 entry
226  
-    Then the JSON at "path" should have 2 entries
227  
-    Then the JSON should have 3 keys
228  
-    Then the JSON should have 4 whatevers
  163
+```cucumber
  164
+Then the JSON should be:
  165
+  """
  166
+  {
  167
+    "key": "value"
  168
+  }
  169
+  """
  170
+Then the JSON at "path" should be:
  171
+  """
  172
+  [
  173
+    "entry",
  174
+    "entry"
  175
+  ]
  176
+  """
  177
+
  178
+Then the JSON should be {"key":"value"}
  179
+Then the JSON at "path" should be {"key":"value"}
  180
+Then the JSON should be ["entry","entry"]
  181
+Then the JSON at "path" should be ["entry","entry"]
  182
+Then the JSON at "path" should be "string"
  183
+Then the JSON at "path" should be 10
  184
+Then the JSON at "path" should be 10.0
  185
+Then the JSON at "path" should be 1e+1
  186
+Then the JSON at "path" should be true
  187
+Then the JSON at "path" should be false
  188
+Then the JSON at "path" should be null
  189
+
  190
+Then the JSON should include:
  191
+  """
  192
+  {
  193
+    "key": "value"
  194
+  }
  195
+  """
  196
+Then the JSON at "path" should include:
  197
+  """
  198
+  [
  199
+    "entry",
  200
+    "entry"
  201
+  ]
  202
+  """
  203
+
  204
+Then the JSON should include {"key":"value"}
  205
+Then the JSON at "path" should include {"key":"value"}
  206
+Then the JSON should include ["entry","entry"]
  207
+Then the JSON at "path" should include ["entry","entry"]
  208
+Then the JSON should include "string"
  209
+Then the JSON at "path" should include "string"
  210
+Then the JSON should include 10
  211
+Then the JSON at "path" should include 10
  212
+Then the JSON should include 10.0
  213
+Then the JSON at "path" should include 10.0
  214
+Then the JSON should include 1e+1
  215
+Then the JSON at "path" should include 1e+1
  216
+Then the JSON should include true
  217
+Then the JSON at "path" should include true
  218
+Then the JSON should include false
  219
+Then the JSON at "path" should include false
  220
+Then the JSON should include null
  221
+Then the JSON at "path" should include null
  222
+
  223
+Then the JSON should have "path"
  224
+
  225
+Then the JSON should be a hash
  226
+Then the JSON at "path" should be an array
  227
+Then the JSON at "path" should be a float
  228
+
  229
+Then the JSON should have 1 entry
  230
+Then the JSON at "path" should have 2 entries
  231
+Then the JSON should have 3 keys
  232
+Then the JSON should have 4 whatevers
  233
+```
229 234
 
230 235
 _All instances of "should" above could be followed by "not" and all instances of "JSON" could be downcased and/or followed by "response."_
231 236
 
232  
-### Table format
  237
+### Table Format
233 238
 
234 239
 Another step exists that uses Cucumber's table formatting and wraps two of the above steps:
235 240
 
236  
-    Then the JSON should have the following:
237  
-      | path/0 | {"key":"value"}   |
238  
-      | path/1 | ["entry","entry"] |
  241
+```cucumber
  242
+Then the JSON should have the following:
  243
+  | path/0 | {"key":"value"}   |
  244
+  | path/1 | ["entry","entry"] |
  245
+```
239 246
 
240 247
 Any number of rows can be given. The step above is equivalent to:
241 248
 
242  
-    Then the JSON at "path/0" should be {"key":"value"}
243  
-    And the JSON at "path/1" should be ["entry","entry"]
  249
+```cucumber
  250
+Then the JSON at "path/0" should be {"key":"value"}
  251
+And the JSON at "path/1" should be ["entry","entry"]
  252
+```
244 253
 
245 254
 If only one column is given:
246 255
 
247  
-    Then the JSON should have the following:
248  
-      | path/0 |
249  
-      | path/1 |
  256
+```cucumber
  257
+Then the JSON should have the following:
  258
+  | path/0 |
  259
+  | path/1 |
  260
+```
250 261
 
251 262
 This is equivalent to:
252 263
 
253  
-    Then the JSON should have "path/0"
254  
-    And the JSON should have "path/1"
  264
+```cucumber
  265
+Then the JSON should have "path/0"
  266
+And the JSON should have "path/1"
  267
+```
255 268
 
256 269
 ### JSON Memory
257 270
 
@@ -259,72 +272,70 @@ There's one more Cucumber step that json_spec provides which hasn't been used ab
259 272
 memorize JSON for reuse in later steps. You can "keep" all or a portion of the JSON by giving a
260 273
 name by which to remember it.
261 274
 
262  
-    Feature: User API
263  
-      Scenario: Index action includes full user JSON
264  
-        Given the following user exists:
265  
-          | id | first_name | last_name |
266  
-          | 1  | Steve      | Richert   |
267  
-        And I visit "/users/1.json"
268  
-        And I keep the JSON response as "USER_1"
269  
-        When I visit "/users.json"
270  
-        Then the JSON response should be:
271  
-          """
272  
-          [
273  
-            %{USER_1}
274  
-          ]
275  
-          """
  275
+```cucumber
  276
+Feature: User API
  277
+  Scenario: Index action includes full user JSON
  278
+    Given the following user exists:
  279
+      | id | first_name | last_name |
  280
+      | 1  | Steve      | Richert   |
  281
+    And I visit "/users/1.json"
  282
+    And I keep the JSON response as "USER_1"
  283
+    When I visit "/users.json"
  284
+    Then the JSON response should be:
  285
+      """
  286
+      [
  287
+        %{USER_1}
  288
+      ]
  289
+      """
  290
+```
276 291
 
277 292
 You can memorize JSON at a path:
278 293
 
279  
-    Given I keep the JSON response at "first_name" as "FIRST_NAME"
  294
+```cucumber
  295
+Given I keep the JSON response at "first_name" as "FIRST_NAME"
  296
+```
280 297
 
281 298
 You can remember JSON at a path:
282 299
 
283  
-    Then the JSON response at "0/first_name" should be:
284  
-      """
285  
-      %{FIRST_NAME}
286  
-      """
  300
+```cucumber
  301
+Then the JSON response at "0/first_name" should be:
  302
+  """
  303
+  %{FIRST_NAME}
  304
+  """
  305
+```
287 306
 
288 307
 You can also remember JSON inline:
289 308
 
290  
-    Then the JSON response at "0/first_name" should be %{FIRST_NAME}
  309
+```cucumber
  310
+Then the JSON response at "0/first_name" should be %{FIRST_NAME}
  311
+```
  312
+
  313
+### More
  314
+
  315
+Check out the [specs](https://github.com/collectiveidea/json_spec/blob/master/spec)
  316
+and [features](https://github.com/collectiveidea/json_spec/blob/master/features) too see all the
  317
+various ways you can use json_spec.
291 318
 
292 319
 Contributing
293 320
 ------------
294  
-In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), **everyone** is encouraged to help improve this project.
295  
-
296  
-Here are some ways *you* can contribute:
297  
-
298  
-* using alpha, beta, and prerelease versions
299  
-* reporting bugs
300  
-* suggesting new features
301  
-* writing or editing documentation
302  
-* writing specifications
303  
-* writing code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace)
304  
-* refactoring code
305  
-* closing [issues](https://github.com/collectiveidea/json_spec/issues)
306  
-* reviewing patches
307  
-
308  
-Submitting an Issue
309  
--------------------
310  
-We use the [GitHub issue tracker](https://github.com/collectiveidea/json_spec/issues) to track bugs
311  
-and features. Before submitting a bug report or feature request, check to make sure it hasn't already
312  
-been submitted. You can indicate support for an existing issuse by voting it up. When submitting a
313  
-bug report, please include a [Gist](https://gist.github.com/) that includes a stack trace and any
314  
-details that may be necessary to reproduce the bug, including your gem version, Ruby version, and
315  
-operating system. Ideally, a bug report should include a pull request with failing specs.
316  
-
317  
-Submitting a Pull Request
318  
--------------------------
319  
-1. Fork the project.
320  
-2. Create a topic branch.
321  
-3. Implement your feature or bug fix.
322  
-4. Add specs for your feature or bug fix.
323  
-5. Run `bundle exec rake`. If your changes are not 100% covered and passing, go back to step 4.
324  
-6. Commit and push your changes.
325  
-7. Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)
  321
+
  322
+If you come across any issues, please [tell us](https://github.com/collectiveidea/json_spec/issues).
  323
+Pull requests (with tests) are appreciated. No pull request is too small. Please help with:
  324
+
  325
+* Reporting bugs
  326
+* Suggesting features
  327
+* Writing or improving documentation
  328
+* Fixing typos
  329
+* Cleaning whitespace
  330
+* Refactoring code
  331
+* Adding tests
  332
+* Closing [issues](https://github.com/collectiveidea/json_spec/issues)
  333
+
  334
+If you report a bug and don't include a fix, please include a failing test.
326 335
 
327 336
 Copyright
328 337
 ---------
  338
+
329 339
 Copyright © 2011 Steve Richert
330  
-See [LICENSE](https://github.com/collectiveidea/json_spec/blob/master/LICENSE.md) for details.
  340
+
  341
+See [LICENSE](https://github.com/collectiveidea/json_spec/blob/master/LICENSE) for details.

0 notes on commit da68e67

Please sign in to comment.
Something went wrong with that request. Please try again.