Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

more README

  • Loading branch information...
commit eb3037296ac39d99fcdf163072a2f95b63bdc682 1 parent 07cfd66
authored April 14, 2009

Showing 1 changed file with 30 additions and 22 deletions. Show diff stats Hide diff stats

  1. 52  README.markdown
52  README.markdown
Source Rendered
@@ -15,17 +15,19 @@ To run all of the specs:
15 15
 
16 16
     rake test:javascripts
17 17
   
18  
-(Hint: You can also use `spec:javascripts` or `examples:javascripts`.  They're all the same.)
  18
+(Hint: You can also use the `spec:javascripts` or `examples:javascripts` aliases.)
19 19
   
20 20
 To run an individual spec file called "application_spec.js":
21 21
 
22 22
     rake test:javascripts TEST=application
23 23
     
24  
-To generate another spec file for a JavaScript file called "public/javascripts/graphics.js" run:
  24
+To generate a spec for a JavaScript file called "public/javascripts/graphics.js" run:
25 25
 
26 26
     ./script/generate javascript_spec graphics
27 27
     rake test:javascripts TEST=graphics
28 28
 
  29
+To run your spec inside a web browser, load the appropriate `HTML fixture` (see below).
  30
+
29 31
 Directory Layout: Specs and Fixtures
30 32
 -------------------------------------
31 33
 
@@ -33,9 +35,9 @@ Directory Layout: Specs and Fixtures
33 35
 
34 36
 The plugin creates a JavaScript spec directories under one of the following directories, depending on which tool you use to test your Ruby code:
35 37
 
36  
-* `examples/javascripts`: if you're using [Micronaut](http://github.com/spicycode/micronaut)
37  
-* `spec/javascripts`: if you're using [RSpec](http://rspec.info/)
38  
-* `test/javascript`: if you're using anything else
  38
+* examples/javascripts: if you're using [Micronaut](http://github.com/spicycode/micronaut)
  39
+* spec/javascripts: if you're using [RSpec](http://rspec.info/)
  40
+* test/javascript: if you're using anything else
39 41
 
40 42
 The layout of the JavaScript spec directories looks like this:
41 43
 
@@ -52,9 +54,9 @@ The layout of the JavaScript spec directories looks like this:
52 54
 ### Why We Need Fixtures
53 55
 This plugin relies on the convention that each spec file will have a similarly named HTML file in the `fixtures` directory.  We create one fixture per spec file so that env.js has a base DOM to emulate when running specs from the command line and so that we have an HTML launch-pad to run our specs in-browser.  
54 56
 
55  
-If you want to have specific HTML for a give suite of specs, put it in the fixture for that suite.  If you want to run a specific suite of tests in Firefox or Internet Explorer, open the HTML fixture file with the same name and Screw.Unit automatically runs.
  57
+If you want to have specific HTML for a suite of specs, put it in the HTML fixture for that suite.  If you want to run a specific suite of tests in Firefox or Internet Explorer, open the HTML fixture file with the same name and Screw.Unit automatically runs.
56 58
 
57  
-Example Spec using jQuery (the default)
  59
+Example Using jQuery
58 60
 ---------------------------------------
59 61
 
60 62
 This plugin is opinionated and assumes you're using jQuery by default.  The plugin itself actually uses jQuery under the covers to run Screw.Unit.
@@ -76,7 +78,7 @@ This plugin is opinionated and assumes you're using jQuery by default.  The plug
76 78
 
77 79
 (By the way, we don’t actually encourage you to write specs and tests for standard libraries like JQuery and Prototype. It just makes for an easy demo.)
78 80
 
79  
-Example using Prototype
  81
+Example Using Prototype
80 82
 -----------------------
81 83
 
82 84
 It's very easy to add support for Prototype.  Here's an example:
@@ -104,7 +106,7 @@ Note that you must do the following:
104 106
 
105 107
 * put jQuery into "no conflict" mode to give the `$` function back to Prototype
106 108
 * require the `prototype.js` file
107  
-* chain any files that are dependent on `prototype.js` being load in an `onload`
  109
+* chain any files that are dependent on `prototype.js` in the `onload` callback
108 110
   
109 111
 JavaScript API
110 112
 --------------
@@ -112,7 +114,7 @@ JavaScript API
112 114
 The JavaScript Testing Rails Plugin provides a small number of functions that help you write specs that run correctly inside a web browser as well from the Rhino command-line test runner.
113 115
 
114 116
 ### require(fileName, [{onload:function}])
115  
-When running from the command line, `require` becomes a Rhino call to `load`, but in a web browser, it dynamically creates a JavaScript `script` tag and loads your given file for you.  It takes an optional `onload` function that will be ran immediately after the given JavaScript file is loaded.  This helps you chain dependencies, especially when running in-browser where each JavaScript file is loaded asynchronously in a separate thread.
  117
+When running from the command line, `require` becomes a Rhino call to `load`, but in a web browser, it dynamically creates a JavaScript `script` tag and loads the given file for you.  It takes an optional `onload` callback function that will be ran immediately after the given JavaScript file is loaded.  This helps you chain dependencies.  This is especially useful when running in-browser where each JavaScript file is loaded asynchronously in a separate thread.
116 118
 
117 119
     require("../../public/javascripts/prerequisite.js", {onload: function() {
118 120
         require("../../public/javascripts/dependent_file1.js");
@@ -123,13 +125,13 @@ When running from the command line, `require` becomes a Rhino call to `load`, bu
123 125
 When running from the command line, `debug` simply prints a message to stdout, but in a web browser it outputs into the DOM directly.  This helps you avoid using the `print` function which prints to stdout in Rhino but actually opens a file print dialog when running in a browser!
124 126
 
125 127
 ### console.debug(message)
126  
-If you use Firebug, you might add a `console.debug` function call in your tests to debug a problem.  Calling this from the command-line however, would blow up.  To make life a little easier, this `console.debug` is just an alias to Rhino's `print` function which will write text to stdout.
  128
+If you use Firebug, you might add a `console.debug` function call in your tests to debug a problem.  Calling this from the command-line would crash, however, because Firebug is missing.  To make life a little easier, this `console.debug` is just an alias to Rhino's `print` function and will write your message to stdout.
127 129
 
128 130
 Extras
129 131
 -------------
130 132
 
131 133
 ### rake js:fixtures
132  
-If you're on Mac OS X, this command opens your JavaScript fixtures directory using Finder to make running specs from a browser a bit easier.  If you're running on Linux, it opens the fixtures directory using Firefox.
  134
+If you're on Mac OS X, this command opens your JavaScript fixtures directory using Finder to make running specs from a browser easy.  If you're running on Linux, it opens the fixtures directory using Firefox.
133 135
 
134 136
 ### rake js:shell
135 137
 Runs an IRB-like JavaScript shell for debugging your JavaScript code.  jQuery and env.js are pre-loaded for you to make debugging DOM code easy.
@@ -158,22 +160,28 @@ Mocking Example with Smoke
158 160
 
159 161
 Tips & Tricks
160 162
 -------------
161  
-* (avoid `print` in your tests; it works fine from command line but causes lots of headaches in browser)
162  
-* don't test jQuery or Prototype, especially event wiring... instead write a separate function, test it, and wire it to events
  163
+* Avoid using `print` in your tests while debugging.  It works fine from the command line but causes lots of headaches in browser.  (Just imagine a print dialog opening ten or fifteen times and then Firefox crashing... this is a mistake I've make too many times!  Trust me!)
  164
+* We don't recommend testing jQuery or Prototype, especially event wiring.  (You don't test Rails do you?)  Instead write a separate function, test it, and wire it to events using jQuery or Prototype.
163 165
 
164 166
 Caveats
165 167
 ----------
166  
-env.js and jQuery 1.3.x do not currently get along well, so the JavaScript Testing Rails Plugin currently uses jQuery 1.2.6 to run command line specs.
  168
+env.js and jQuery 1.3.x do not currently get along well (as of 2009-04-14), so the JavaScript Testing Rails Plugin currently uses jQuery 1.2.6 to run command line specs.  This is currently in active development, and any help is very appreciated!
167 169
 
  170
+Contributing
  171
+------------
  172
+Fork the [Relevance repo on GitHub](http://www.github.com/relevance/javascript_testing) and start hacking!  If you have patches, send us pull requests.  Also, ([env.js](http://github.com/thatcher/env-js)), [Smoke](http://github.com/andykent/smoke), and [Screw.Unit](http://github.com/nkallen/screw-unit) can use your love too!
168 173
 
169 174
 Links
170 175
 -------------
171  
-* [http://github.com/relevance/javascript_testing](http://github.com/relevance/javascript_testing)
172  
-* [http://blog.thinkrelevance.com/2008/7/31/fully-headless-jsspec](http://blog.thinkrelevance.com/2008/7/31/fully-headless-jsspec)
173  
-* link to screw.unit
174  
-* link to smoke
175  
-* link to env.js
176  
-* link to rhino
  176
+* [JavaScript Testing Rails Plugin](http://github.com/relevance/javascript_testing)
  177
+* [Justin Gehtland's "Fully Headless JSSpec" Blog](http://blog.thinkrelevance.com/2008/7/31/fully-headless-jsspec)
  178
+* [Screw.Unit](http://github.com/nkallen/screw-unit)
  179
+* [Screw.Unit Mailing List](http://groups.google.com/group/screw-unit)
  180
+* [Smoke](http://github.com/andykent/smoke)
  181
+* [env.js](http://www.envjs.com) ([Github](http://github.com/thatcher/env-js))
  182
+* [env.js Mailing List](http://groups.google.com/group/envjs)
  183
+* [Mozilla Rhino](http://www.mozilla.org/rhino/)
  184
+* [W3C DOM Specifications](http://www.w3.org/DOM/DOMTR)
177 185
 
178 186
 Contributors
179 187
 ------------
@@ -186,7 +194,7 @@ Contributors
186 194
 
187 195
 Copyrights
188 196
 ------------
189  
-* Copyright © 2008-2009 Relevance, Inc., under the MIT license
  197
+* Copyright © 2008-2009 [http://www.thinkrelevance.com/](Relevance, Inc.), under the MIT license
190 198
 * env.js     - Copyright 2007-2009 John Resig, under the MIT License
191 199
 * Screw.Unit - Copyright 2008 Nick Kallen, license attached
192 200
 * Rhino      - Copyright 2009 Mozilla Foundation, GPL 2.0

0 notes on commit eb30372

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