jspec 2.11.13 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. data/History.md +714 -0
  2. data/Manifest +51 -36
  3. data/README.md +968 -0
  4. data/Rakefile +4 -53
  5. data/bin/jspec +93 -224
  6. data/jspec.gemspec +5 -5
  7. data/lib/images/sprites.png +0 -0
  8. data/lib/jspec.css +2 -2
  9. data/lib/jspec.growl.js +115 -0
  10. data/lib/jspec.jquery.js +1 -1
  11. data/lib/jspec.js +98 -101
  12. data/lib/jspec.shell.js +5 -2
  13. data/lib/jspec.timers.js +1 -1
  14. data/lib/jspec.xhr.js +12 -2
  15. data/spec/commands/example_command.rb +19 -0
  16. data/spec/dom.html +33 -0
  17. data/spec/node.js +32 -0
  18. data/spec/rhino.js +24 -0
  19. data/spec/ruby/bin/init_spec.rb +101 -0
  20. data/spec/ruby/bin/install_spec.rb +141 -0
  21. data/spec/ruby/bin/run_spec.rb +0 -0
  22. data/spec/ruby/bin/shell_spec.rb +13 -0
  23. data/spec/ruby/bin/spec_helper.rb +25 -0
  24. data/spec/ruby/bin/update_spec.rb +72 -0
  25. data/spec/server.html +29 -0
  26. data/spec/server.rb +1 -1
  27. data/spec/{env.js → support/env.js} +554 -664
  28. data/spec/support/jquery.js +4376 -0
  29. data/spec/{helpers.js → unit/helpers.js} +2 -0
  30. data/spec/{spec.fixtures.js → unit/spec.fixtures.js} +0 -1
  31. data/spec/{spec.grammar-less.js → unit/spec.grammar-less.js} +0 -0
  32. data/spec/{spec.grammar.js → unit/spec.grammar.js} +1 -11
  33. data/spec/{spec.jquery.js → unit/spec.jquery.js} +0 -17
  34. data/spec/{spec.jquery.xhr.js → unit/spec.jquery.xhr.js} +13 -2
  35. data/spec/unit/spec.js +187 -0
  36. data/spec/{spec.matchers.js → unit/spec.matchers.js} +141 -66
  37. data/spec/{spec.modules.js → unit/spec.modules.js} +0 -0
  38. data/spec/{spec.shared-behaviors.js → unit/spec.shared-behaviors.js} +0 -0
  39. data/spec/{spec.utils.js → unit/spec.utils.js} +123 -22
  40. data/spec/{spec.xhr.js → unit/spec.xhr.js} +11 -10
  41. data/{server → src}/browsers.rb +23 -0
  42. data/{server → src}/helpers.rb +2 -17
  43. data/src/installables.rb +229 -0
  44. data/src/project.rb +340 -0
  45. data/{server → src}/routes.rb +1 -1
  46. data/{server → src}/server.rb +0 -0
  47. data/support/js.jar +0 -0
  48. data/templates/default/History.md +5 -0
  49. data/templates/default/{README.rdoc → Readme.md} +3 -3
  50. data/templates/default/lib/{yourlib.core.js → yourlib.js} +0 -0
  51. data/templates/default/spec/commands/example_command.rb +19 -0
  52. data/templates/default/spec/{spec.dom.html → dom.html} +5 -3
  53. data/templates/default/spec/rhino.js +10 -0
  54. data/templates/default/spec/server.html +18 -0
  55. data/templates/default/spec/unit/spec.helper.js +0 -0
  56. data/templates/default/spec/{spec.core.js → unit/spec.js} +0 -0
  57. data/templates/rails/commands/example_commands.rb +19 -0
  58. data/templates/rails/{spec.dom.html → dom.html} +4 -2
  59. data/templates/rails/rhino.js +10 -0
  60. data/templates/rails/server.html +18 -0
  61. data/templates/rails/unit/spec.helper.js +0 -0
  62. data/templates/rails/{spec.application.js → unit/spec.js} +0 -0
  63. metadata +56 -41
  64. data/History.rdoc +0 -590
  65. data/README.rdoc +0 -842
  66. data/spec/async +0 -1
  67. data/spec/jquery.js +0 -19
  68. data/spec/spec.dom.html +0 -34
  69. data/spec/spec.js +0 -166
  70. data/spec/spec.node.js +0 -46
  71. data/spec/spec.rhino.js +0 -23
  72. data/spec/spec.server.html +0 -29
  73. data/templates/default/History.rdoc +0 -4
  74. data/templates/default/spec/spec.rhino.js +0 -8
  75. data/templates/default/spec/spec.server.html +0 -16
  76. data/templates/rails/spec.rhino.js +0 -8
  77. data/templates/rails/spec.server.html +0 -16
data/README.rdoc DELETED
@@ -1,842 +0,0 @@
1
-
2
- = JSpec
3
-
4
- JSpec is a minimalistic JavaScript behavior driven development framework,
5
- providing simple installation, extremely low learning curve, absolutely no pollution
6
- to core prototypes, async request support, and incredibly sexy syntax, tons of matchers
7
- and much more.
8
-
9
- == Features
10
-
11
- * Highly readable
12
- * Framework / DOM independent
13
- * Modular via JSpec Module's and hooks
14
- * Mock Ajax Requests
15
- * Rhino support
16
- * Env.js support
17
- * Async support
18
- * Fixture support
19
- * Ruby JavaScript testing server
20
- * Nested describes
21
- * Does not pollute core object prototypes
22
- * Cascading before/after/before_each/after_each hooks
23
- * Extremely simple and intuitive matcher declaration
24
- * Over 45 core matchers
25
- * Allows parens to be optional when using matchers to increase readability
26
- * Several helpful formatters (DOM, Console, Terminal, ...)
27
- * Assertion graphs displaying how many, and which assertions pass or failed
28
- * Default / customizable evaluation contexts
29
- * DOM sandbox support
30
- * Great looking default DOM theme
31
- * `jspec` command-line utility for auto-running specs, and initializing project templates
32
- * Proxy or 'Spy' assertions
33
- * Method Stubbing
34
- * Shared behaviors
35
- * Profiling
36
- * Interactive Shell
37
- * Ruby on Rails Integration
38
- * Tiny (15 kb compressed, 1300-ish LOC)
39
-
40
- == Installation
41
-
42
- Simply download JSpec and include JSpec.css and JSpec.js in your markup.
43
- Head over to the downloads section on Github, clone this public repo, or
44
- add JSpec as a git submodule with in your project. Alternatively JSpec is
45
- also available as a Ruby Gem (though this is not required), which also
46
- provides the `jspec` executable. First install [Gemcutter](http://gemcutter.org/) then execute:
47
- $ sudo gem install jspec
48
-
49
- At which point you may:
50
- $ jspec init myproject
51
-
52
- By default, the command above will use absolute path for all JSpec library files.
53
- This behavior can be a problem when you're working across different computers or
54
- operating systems. You can freeze the library or symlink it.
55
-
56
- $ jspec init myproject --freeze
57
- $ jspec init myproject --symlink
58
-
59
- JSpec scripts should NOT be referenced via the <script> tag, they should be
60
- loaded using the exec method (unless you are using the grammar-less alternative).
61
- Below is an example:
62
-
63
- ...
64
- <script>
65
- function runSuites() {
66
- JSpec
67
- .exec('spec.core.js')
68
- .exec('spec.jquery.js')
69
- .run({ failuresOnly : true })
70
- .report()
71
- }
72
- </script>
73
- <body onLoad="runSuites()">
74
- ...
75
-
76
- You may optionally want to use sources in the /pkg directory
77
- for your project, since it includes compressed alternatives generated
78
- each release.
79
-
80
- == Cheat Sheet
81
-
82
- Using the bash cheat sheet library found at http://github.com/visionmedia/ch
83
- we can get quick cheat sheets for many aspects of development including JSpec!
84
-
85
- $ cd /tmp && git clone git://github.com/visionmedia/ch.git && cd ch && sudo make install && ch jspec
86
-
87
- == Example
88
-
89
- describe 'ShoppingCart'
90
- before_each
91
- cart = new ShoppingCart
92
- end
93
-
94
- describe 'addProducts'
95
- it 'should add several products'
96
- cart.addProduct('cookie')
97
- cart.addProduct('icecream')
98
- cart.should.have 2, 'products'
99
- end
100
- end
101
-
102
- describe 'checkout'
103
- it 'should throw an error when checking out with no products'
104
- -{ cart.clear().checkout() }.should.throw_error EmptyCart
105
- end
106
- end
107
- end
108
-
109
- == Grammar-less Example
110
-
111
- JSpec's grammar is optional, you may also use the equivalent grammar-less
112
- alternative below using pure JavaScript (when using the JSpec grammar you
113
- may also use grammar-less assertions):
114
-
115
- JSpec.describe('ShoppingCart', function(){
116
- before_each(function{
117
- cart = new ShoppingCart
118
- })
119
-
120
- describe('addProducts', function(){
121
- it ('should add several products', function(){
122
- cart.addProducts('cookie')
123
- cart.addProducts('icecream')
124
- expect(cart).to(have, 2, 'products')
125
- })
126
- })
127
-
128
- describe('checkout', function(){
129
- it ('should throw an error when checking out with no products', function(){
130
- expect(function(){ cart.clear().checkout() }).to(throw_error, EmptyCart)
131
- })
132
- })
133
- })
134
-
135
- == Options
136
-
137
- You may alter the way JSpec operates by assigning options via the
138
- JSpec.options hash, by passing string-based option values via the
139
- query string, or passing a hash to run(). For example
140
- JSpec.options.failuresOnly = true, and ?failuresOnly=1 will both work.
141
-
142
- * profile {bool} when enabled, uses console.time() in order to display performance information in your console log as specs are completed. (DOM, Console)
143
- * failuresOnly {bool} displays only failing specs, making them quick to discover and fix (DOM, Terminal, Server)
144
- * reportToId {string} an element id to report to when using the DOM formatter (DOM)
145
- * verbose {bool} verbose server output, defaults to false (Server)
146
-
147
- == Matchers
148
-
149
- * Core
150
-
151
- - equal, be ===
152
- - be_a, be_an have constructor of x
153
- - be_an_instance_of instanceof x
154
- - be_at_least >=
155
- - be_at_most <=
156
- - be_null == null
157
- - be_empty length < 0 or {}
158
- - be_true == true
159
- - be_false == false
160
- - be_type be type of x
161
- - be_greater_than >
162
- - be_less_than <
163
- - be_undefined check if variable passed is undefined
164
- - throw_error should throw an error, optionally supply the error string or regexp for message comparison
165
- - have object should have n of property (person.should.have(2, 'pets'))
166
- - have_at_least object should have at least n of property
167
- - have_at_most object should have a maximum n of property
168
- - have_within object should have within n..n of property (person.should.have_within(1..3, 'pets')
169
- - have_length length of n
170
- - have_prop object should have property x, optionally supplying an expected value
171
- - have_property strict version of have_prop
172
- - be_within checks if n is within the range passed
173
- - include include substring, array element, or hash key
174
- - match string should match regexp x
175
- - respond_to property x should be a function
176
- - eql matches simple literals (strings, numbers) with ==
177
- However composites like arrays or 'hashes' are recursively matched,
178
- meaning that [1, 2, [3]].should_eql([1, 2, [3]]) will be true.
179
-
180
- * jQuery
181
-
182
- - have_tag, have_one have exactly one tag
183
- - have_tags, have_many have more than one tag
184
- - have_child have exactly one child
185
- - have_children have more than one child
186
- - have_text have plain text
187
- - have_attr have an attribute, with optional value
188
- - have_type
189
- - have_id
190
- - have_title
191
- - have_alt
192
- - have_href
193
- - have_rel
194
- - have_rev
195
- - have_name
196
- - have_target
197
- - have_value
198
- - have_class
199
- - have_classes
200
- - be_visible
201
- - be_hidden
202
- - be_enabled
203
- - be_disabled
204
- - be_selected
205
- - be_checked
206
-
207
- == Async Support With Mock Timers
208
-
209
- The javascript mock timers library is available at http://github.com/visionmedia/js-mock-timers
210
- although it is already bundled with JSpec at lib/jspec.timers.js
211
-
212
- Timers return ids and may be passed to clearInterval(), however
213
- they do not execute in threads, they must be manually scheduled and
214
- controlled via the tick() function.
215
-
216
- setTimeout(function(){
217
- alert('Wahoo!')
218
- }, 400)
219
-
220
- tick(200) // Nothing happens
221
- tick(400) // Wahoo!
222
-
223
- setInterval() works as expected, although it persists, where as setTimeout()
224
- is destroyed after a single call. As conveyed by the last tick() call below,
225
- a large increment in milliseconds may cause the callbacks to be called several times
226
- to 'catch up'.
227
-
228
- progress = ''
229
- var id = setInterval(function(){
230
- progress += '.'
231
- }, 100)
232
-
233
- tick(50), print(progress) // ''
234
- tick(50), print(progress) // '.'
235
- tick(100), print(progress) // '..'
236
- tick(100), print(progress) // '...'
237
- tick(300), print(progress) // '......'
238
-
239
- clearInterval(id)
240
-
241
- tick(800) // Nothing happens
242
-
243
- You may also reset at any time using resetTimers()
244
-
245
- == Proxy Assertions
246
-
247
- Proxy or 'Spy' assertions allow you to assert that a method is called n number
248
- of times, with x arguments, returning x value. For example:
249
-
250
- person = { getPets : function(species){ return ['izzy'] }}
251
- person.should.receive('getPets', 'twice').with_args(an_instance_of(String))and_return(['izzy'])
252
- person.getPets('dog') // This will pass
253
- person.getPets() // This will fail because we asked an instance of String
254
-
255
- This is a useful mechanism for testing the behavior of your object, as well as
256
- how other methods may interact with it. Below is another example:
257
-
258
- array = ['foo', 'bar']
259
- array.should.receive('toString').and_return('foo,bar')
260
- 'array: ' + array // This line causes the spec to pass due to calling toString()
261
-
262
- For more examples view spec/spec.matchers.js
263
-
264
- == Method Stubbing
265
-
266
- JSpec currently provides very simple stubbing support shown below:
267
-
268
- person = { toString : function(){ return '<Person>' } }
269
- stub(person, 'toString').and_return('Ive been stubbed!')
270
-
271
- After each spec all stubs are restored to their original methods so
272
- there is no reason to explicitly call destub(). To persist stubs,
273
- use a before_each hook:
274
-
275
- before_each
276
- stub(someObject, 'method').and_return({ some : thing })
277
- end
278
-
279
- To destub a method simply call destub() at any time:
280
-
281
- destub(person, 'toString')
282
-
283
- If you would like to whipe an object clear of stubs simply pass it
284
- to destub() without an additional method argument:
285
-
286
- destub(person)
287
-
288
- Alternatively both these utility functions may be called as methods
289
- on any object when using the JSpec grammar:
290
-
291
- someObject.stub('method').and_return('whatever')
292
- // Converted to stub(someObject, 'method').and_return('whatever')
293
-
294
- == Helpers
295
-
296
- * Core
297
-
298
- - an_instance_of used in conjunction with the 'receive' matcher
299
- - mockRequest, mock_request mock a request (requires jspec.xhr.js)
300
- - unmockRequest, unmock_request unmock requests (requests jspec.xhr.js)
301
-
302
- * jQuery
303
-
304
- - sandbox used to generate new DOM sandbox, using jQuery object
305
- - element same as invoking jQuery, just reads better and no need to worry about $ collisions
306
- - elements alias of element
307
-
308
- == Shared Behaviors
309
-
310
- JSpec's support for shared behaviors allows multiple suites or describe blocks to share
311
- common functionality. For example an Admin, would inherit all specs of User:
312
-
313
- describe 'User'
314
- before
315
- User = function(name) { this.name = name }
316
- user = new User('joe')
317
- end
318
-
319
- it 'should have a name'
320
- user.should.have_property 'name'
321
- end
322
-
323
- describe 'Administrator'
324
- should_behave_like('User')
325
-
326
- before
327
- Admin = function(name) { this.name = name }
328
- Admin.prototype.may = function(perm){ return true }
329
- user = new Admin('tj')
330
- end
331
-
332
- it 'should have access to all permissions'
333
- user.may('edit pages').should.be_true
334
- end
335
- end
336
- end
337
-
338
- NOTE: both User and Administrator's before hooks implement the 'user' variable
339
-
340
- == Mock Ajax Requests
341
-
342
- JSpec supports generic Ajax mocking which is usable with any JavaScript framework via 'jspec.xhr.js'. The
343
- API is comprised of two functions, mockRequest() and unmockRequest(). unmockRequest() is
344
- automatically called after each specification to restore the default functionality of XMLHttpRequest,
345
- so it is uncommon to call unmockRequest() directly. Below is a jQuery example:
346
-
347
- it 'should mock requests'
348
- mockRequest().and_return('{ foo : "bar" }', 'application/json')
349
- $.getJSON('foo', function(response, statusText){
350
- response.foo.should.eql 'bar'
351
- })
352
- end
353
-
354
- The mockRequest().and_return signature is as follows:
355
-
356
- mockRequest().and_return(<data>, [content-type], [response-status-code], [headers-hash])
357
-
358
- At the moment mockRequest() itself does not accept any arguments, however in the future
359
- this will be used to target specific uris for mocking.
360
-
361
- NOTE: works with Rhino as well
362
-
363
- == Hooks
364
-
365
- Currently the following hooks are supported, and may be utilized any number of times as they
366
- are simply pushed to a stack. So for instance you may have two before_each blocks within the same
367
- scope, they will both run, but this can help keep your specs readable.
368
-
369
- * before run once before the suite is executed
370
- * after run once after the suite is executed
371
- * before_each run before each specification
372
- * after_each run after each specification
373
-
374
- == Custom Contexts
375
-
376
- Custom contexts can be applied to supply helper
377
- methods or properties to all subsequent bodies (other hooks, or specs).
378
-
379
- Keep in mind that when replacing the default context you will loose
380
- functionality provided by it, unless you manually merge it with your
381
- custom context.
382
-
383
- To reset the context simply assign null to obtain the original context.
384
-
385
- ...
386
- before
387
- JSpec.context = { foo : 'bar' }
388
- end
389
-
390
- after
391
- JSpec.context = null
392
- end
393
-
394
- it 'will work ;)'
395
- foo.should_equal 'bar'
396
- end
397
- ...
398
-
399
- == Async Support
400
-
401
- Currently only jspec.jquery.js supports async requests. JSpec uses jQuery.ajaxSetup and sets all
402
- requests to sync, which preserves execution order, and reports correctly.
403
-
404
- it 'should load mah cookies (textfile)'
405
- $.post('async', function(text){
406
- text.should_eql 'cookies!'
407
- })
408
- end
409
-
410
- == Pre-processor
411
-
412
- The pre-processing capability of JSpec is extremely powerful. Your JavaScript
413
- code is not necessarily what it seems. For example when you seemingly invoke a
414
- object's prototype like below:
415
-
416
- 'foobar'.should.include 'bar'
417
-
418
- First parens are added:
419
-
420
- 'foobar'.should.include('bar')
421
-
422
- Secondly the matcher invocation is converted to a non-polluting match() call:
423
-
424
- JSpec.match('foobar', 'should', 'include', 'bar')
425
-
426
- This also means instead of:
427
-
428
- var object = { foo : 'bar' }
429
- object.should.include 'foo'
430
-
431
- We can do:
432
-
433
- { foo : 'bar' }.should.include 'foo'
434
-
435
- === Closure Literal
436
-
437
- These are equivalent:
438
-
439
- -{ throw 'test' }.should.throw_error
440
- function() { throw 'test' }.should.throw_error
441
-
442
- === Inclusive Range Literal
443
-
444
- The following expands to the array of [1,2,3,4,5]
445
-
446
- n.should.be_within 1..5
447
-
448
- === __END__
449
-
450
- Any text placed after __END__ is considered irrelevant and
451
- is striped out before evaluation. This is sometimes useful for
452
- document or code reference while writing specs.
453
-
454
- For example when writting regression specs it is sometimes useful
455
- to paste the issue ticket's comment(s) below this area for reference.
456
-
457
- == Formatters
458
-
459
- To change a formatter simply alter the options hash like below, assigning
460
- a new constructor, or pass it within the hash to run():
461
-
462
- JSpec.options.formatter = JSpec.formatters.Console
463
-
464
- OR
465
-
466
- JSpec
467
- .exec('...')
468
- .run({ formatter : JSpec.formatters.Terminal })
469
- .report()
470
-
471
- == Fixtures
472
-
473
- The fixture() utility function may be used in order to load arbitrary file contents
474
- for use with your specifications. JSpec will resolve fixture('data') in the following
475
- manor:
476
-
477
- - 'data'
478
- - 'spec/data'
479
- - 'spec/fixtures/data'
480
- - 'spec/fixtures/data.html'
481
-
482
- So if the file 'spec/fixtures/data.html' exists, we can simply use fixture('data'),
483
- where as 'spec/fixtures/xml/data.xml' must be specified with fixture('xml/data.xml').
484
-
485
- If you prefer not to store fixtures in the 'fixtures' directory you must be more specific
486
- with the path supplied.
487
-
488
- == Testing DOM Elements
489
-
490
- When using jQuery testing DOM elements is very easy. Many may think they require specific
491
- sandbox divs in their html, however you do not. Using the fixture support mentioned above
492
- you may simply load some HTML, and use the 'elements()' utility which is an alias of jQuery:
493
-
494
- describe 'JSpec DOM testing'
495
- describe 'is so easy'
496
- before_each
497
- list = elements(fixture('users-list'))
498
- // or list = jQuery(fixture('users-list'))
499
- // or list = $(fixture('users-list'))
500
- end
501
-
502
- it 'should have users'
503
- list.should.have_tag 'ul'
504
- end
505
- end
506
- end
507
-
508
- You may also use simple strings, since jQuery's constructor will convert them to DOM elements:
509
-
510
- describe 'Something'
511
- before_each
512
- html = elements('<p>Foo</p>')
513
- // or html = $('<p>Foo</p>') ...
514
- end
515
-
516
- it 'should do something'
517
- html.should.have_text 'Foo'
518
- end
519
- end
520
-
521
- == Custom Matchers
522
-
523
- First lets create a simple equality matcher. In the case below JSpec is smart enough to realize
524
- this is simply a binary operator, and simply transforms this into 'actual === expected'
525
-
526
- JSpec.addMatchers({
527
- equal : '==='
528
- })
529
-
530
- To alias a method to keep your specs readable you may alias them like below:
531
-
532
- JSpec.addMatchers({
533
- be : 'alias equal'
534
- })
535
-
536
- 'foo'.should.equal 'foo'
537
- true.should.be true
538
-
539
- Matchers with string bodies implicitly return the expression value.
540
- The expanded version of the equal matcher would then be:
541
-
542
- JSpec.addMatchers({
543
- equal : 'actual === expected'
544
- })
545
-
546
- Large matchers or those which require several parameters may wish
547
- to utilize the hash method:
548
-
549
- JSpec.addMatchers({
550
- equal : { match : function(actual, expected){
551
- return actual === expected
552
- }}
553
- })
554
-
555
- To keep JSpec tiny, JSpec will default to generating failure messages
556
- for you, how ever this can be explicitly defined:
557
-
558
- JSpec.addMatchers({
559
- equal : {
560
- match : function(actual, expected){
561
- return actual === expected
562
- },
563
- message : function(actual, expected, negate) {
564
- return 'a message here'
565
- }
566
- }
567
- })
568
-
569
- When defining matchers that are extremely similar in functionality, however
570
- require different names, you may use a prefixed list of words like below which
571
- defines be_disabled, be_selected, be_checked, and have_type, have_id, etc. Each
572
- function must return the matcher body which will be used.
573
-
574
- JSpec.addMatchers({
575
- 'be disabled selected checked' : function(attr) {
576
- return 'jQuery(actual).attr("' + attr + '")'
577
- },
578
-
579
- 'have type id title alt href src sel rev name target' : function(attr) {
580
- return function(actual, value) {
581
- return value ? jQuery(actual).attr(attr) == value:
582
- jQuery(actual).attr(attr)
583
- }
584
- }
585
- })
586
-
587
- == Extending Or Hooking Into JSpec
588
-
589
- JSpec provides a hook architecture for extending or analyzing various
590
- points in its execution, through the use of 'Modules'. For a Module
591
- example view lib/jspec.jquery.js.
592
-
593
- The following methods or properties are utilized by JSpec:
594
-
595
- - name : module name string
596
- - init : called to initialize a module
597
- - formatters : hash of formatters merged with JSpec.formatters
598
- - utilities : hash of utility functions merged with JSpec.defaultContext
599
- - matchers : hash of matchers merged with JSpec's core matchers via JSpec.addMatchers()
600
- - DSLs : hash of DSL methods; for example DSLs.snake contains before_each, after_each, etc.
601
- Where as DSLs.camel may contain beforeEach, afterEach, etc.
602
-
603
- Below is a list of hooks, descriptions, and valid return values which
604
- may simply be implemented as module methods. beforeSuite, afterSuite, beforeSpec, and afterSpec have lower
605
- precedence than before_each, after_each etc within the specs themselves, allowing them to override or undo
606
- anything that has been done by a Module.
607
-
608
- - running(options) : started running JSpec with the options passed : returning 'stop' will halt running
609
- - loading(file) : loading a file : returning 'stop' will prevent loading
610
- - executing(file) : executing a file : returning 'stop' will prevent execution
611
- - posting(data, url) : posting data to a url : returning 'stop' will prevent request
612
- - preprocessing(input) : before input string is preprocessed : return input string for next hook to preprocess
613
- - stubbing(object, method, result) : called when stubbing an object's method, and return value (result). : (no return value)
614
- - requiring(dependency, message) : requiring a dependency : (no return value)
615
- - beforeAssertion(assertion) : before an assertion has been made : (no return value)
616
- - afterAssertion(assertion) : after an assertion has been made : (no return value)
617
- - addingMatcher(name, body) : unprocessed matcher name and body : (no return value)
618
- - addingSuite(suite) : adding Suite instance to JSpec : (no return value)
619
- - beforeSuite(suite) : before running of suite (describe block) : (no return value)
620
- - afterSuite(suite) : after running of suite (describe block) : (no return value)
621
- - beforeSpec(spec) : before running of spec (it block) : (no return value)
622
- - afterSpec(spec) : after running of spec (it block) : (no return value)
623
- - reporting(options) : called before reporting : (no return value)
624
- - evaluatingBody(dsl, matchers, context, contents) : evaluating body contents, with the given context, matchers and dsl. : (no return value)
625
-
626
- For example you may wish to proxy files which are being executed, simply implement the
627
- executing method like below. This example will stop execution of any file matching /matchers/.
628
-
629
- MyModule = {
630
- executing : function(file) {
631
- if (file.match(/matchers/))
632
- return 'stop'
633
- }
634
- }
635
- JSpec.include(MyModule)
636
-
637
- Immutable values may also be passed to hooks using hookImmutable() internally. This allows
638
- for simple numbers, strings, etc to be utilized or altered within a hook implementation. Below
639
- is an example module which adds functionality to the JSpec grammar by converting SomeObject.stub('method')
640
- to stub(SomeObject, 'method'):
641
-
642
- JSpec.include({
643
- preprocessing : function(input) {
644
- return input.replace(/(\w+)\.(stub|destub)\((.*?)\)$/gm, '$2($1, $3)')
645
- }
646
- })
647
-
648
- == JSpec Command-line Utility
649
-
650
- When installed as a Ruby Gem, the `jspec` executable will become available,
651
- allowing you to initialize project templates quickly, as well as auto-testing
652
- specifications when a file is altered.
653
-
654
- Initialize JSpec-driven project template in directory 'myproject':
655
- $ jspec init myproject
656
-
657
- Once within 'myproject' start testing by executing:
658
- $ jspec
659
-
660
- For additional usage execute:
661
- $ jspec help
662
-
663
- Or for specific usage:
664
- $ jspec help run
665
-
666
- == Rhino
667
-
668
- JSpec provides transparent support for Rhino, while using the Terminal formatter.
669
- Simply create a JavaScript file with contents similar to below, and then execute
670
- the command following it:
671
-
672
- load('lib/jspec.js')
673
-
674
- JSpec
675
- .exec('spec/spec.grammar.js')
676
- .exec('spec/spec.core.js')
677
- .run({ formatter : JSpec.formatters.Terminal, failuresOnly : true })
678
- .report()
679
-
680
- Initialize project with:
681
- $ jspec init myproject
682
-
683
- Run with:
684
- $ jspec run --rhino
685
-
686
- Or bind (automated testing):
687
- $ jspec --rhino
688
-
689
- == Server
690
-
691
- The Ruby JavaScript testing server included with JSpec simply runs
692
- the spec suites within each browser you specify, while reporting result
693
- back to the terminal. It is essentially the same as using the DOM formatter
694
- and auto-testing each browser, however results are centralized to the terminal,
695
- removing the need to manually view each browser's output.
696
-
697
- When utilizing the server if a file named spec/jspec.rb (or jspec/jspec.rb for rails)
698
- is present, then it will be loaded before the server is started. This allows you to
699
- add Sinatra routes, support additional Browsers, etc.
700
-
701
- Run with all supported browsers:
702
- $ jspec run --server
703
-
704
- Run with specific browsers:
705
- $ jspec run --browsers Safari,Firefox,Chrome,Explorer
706
-
707
- Run with alternative browser names:
708
- $ jspec run --browsers safari,ff,chrome,ie
709
-
710
- Browsers supported in core:
711
- Browser::Safari
712
- Browser::Chrome
713
- Browser::Opera
714
- Browser::Firefox
715
- Browser::IE
716
-
717
- Supplied routes:
718
- /slow/NUMBER
719
- /status/NUMBER
720
-
721
- For example $.get('/slow/4', function(){}) will take 4 seconds
722
- to reply, where as $.get('/status/404', function(){}) will respond
723
- with an 404 status code. Add additional Sinatra routes to the jspec.rb
724
- file to add your own functionality.
725
-
726
- == Interactive Shell
727
-
728
- JSpec provides an interactive shell through Rhino, utilize with:
729
-
730
- $ jspec shell
731
-
732
- Or to specify additional files to load:
733
-
734
- $ jspec shell lib/*.js
735
-
736
- Or view additional shell help
737
-
738
- $ jspec help shell
739
-
740
- == Ruby on Rails
741
-
742
- No additional gems are required for JSpec to work with rails, although
743
- http://github.com/bhauman/jspec-rails has been created by 'bhauman'. JSpec
744
- supports Rails out of the box, simply execute:
745
-
746
- $ jspec init --rails
747
-
748
- Then while still in the root directory of your Rails project, run the following
749
- command which will bind to, and refresh your browsers automatically when any changes
750
- are made to ./public/javascripts/*.js or ./jspec/*.js
751
-
752
- $ jspec
753
-
754
- Or just like regular JSpec applications, run once:
755
-
756
- $ jspec run
757
-
758
- Or run via the terminal using Rhino:
759
-
760
- $ jspec run --rhino
761
-
762
- == Support Browsers
763
-
764
- Browsers below are supported and can be found in server/browsers.rb, however
765
- your spec/server.rb file may support additional browsers.
766
-
767
- * Safari
768
- * Chrome
769
- * Firefox
770
- * Opera
771
- * Internet Explorer
772
-
773
- == Known Issues
774
-
775
- * The preprocessor is not (yet) capable of multiline conversions. For example the following is invalid
776
-
777
- object.stub('getContentsOfURL').and_return(function(url){
778
- return 'html'
779
- })
780
-
781
- In cases such as this, you may always revert to utilizing JSpec in a grammar-less form as follows:
782
-
783
- stub(object, 'getContentsOfURL').and_return(function(url){
784
- return 'html'
785
- })
786
-
787
- == Additional JSpec Modules
788
-
789
- * JSocka stubbing http://github.com/gisikw/jsocka/tree/master
790
-
791
- == More Information
792
-
793
- * Google Group http://groups.google.com/group/jspec
794
- * IRC Channel irc://irc.freenode.net#jspec
795
- * Featured article in JSMag: http://www.jsmag.com/main.issues.description/id=21/
796
- * Syntax comparison with other frameworks http://gist.github.com/92283
797
- * Get the TextMate bundle at https://github.com/visionmedia/jspec.tmbundle/tree
798
- * For more information consult the JSpec source code documentation or visit http://visionmedia.github.com/jspec
799
- * jQuery + HTML fixture example http://gist.github.com/147831
800
- * Follow 'tjholowaychuk' on twitter
801
-
802
- == Contributors
803
-
804
- Many ideas and bug reports were contributed by
805
- the following developers, thankyou for making
806
- JSpec more enjoyable, and bug free ;)
807
-
808
- * Lawrence Pit
809
- * mpd@jesters-court.ne
810
- * Sarah Brown
811
- * kevin.gisi@gmail.com
812
- * tony_t_tubbs@yahoo.com
813
- * enno84@gmx.net
814
- * fnando
815
- * Tobias Svensson
816
-
817
- == License
818
-
819
- (The MIT License)
820
-
821
- Copyright (c) 2008 - 2009 TJ Holowaychuk <tj@vision-media.ca>
822
-
823
- Permission is hereby granted, free of charge, to any person obtaining
824
- a copy of this software and associated documentation files (the
825
- 'Software'), to deal in the Software without restriction, including
826
- without limitation the rights to use, copy, modify, merge, publish,
827
- distribute, sublicense, and/or sell copies of the Software, and to
828
- permit persons to whom the Software is furnished to do so, subject to
829
- the following conditions:
830
-
831
- The above copyright notice and this permission notice shall be
832
- included in all copies or substantial portions of the Software.
833
-
834
- THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
835
- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
836
- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
837
- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
838
- CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
839
- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
840
- SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
841
-
842
-