Browse files

Updated documentation for assertions.

  • Loading branch information...
1 parent fbd8add commit cb186f6500cf01762447f6d79f093a5ecb2d7fe7 @assaf committed Dec 5, 2012
Showing with 198 additions and 122 deletions.
  1. +169 −111 doc/new/README.md
  2. +19 −6 doc/new/{ → scripts}/generate.coffee
  3. +3 −3 doc/new/{ → scripts}/server.coffee
  4. +7 −2 doc/new/style/zombie.css
View
280 doc/new/README.md
@@ -2,38 +2,38 @@
## Browser
-#### `browser.assert`
+#### browser.assert
Methods for making assertions against the browser, such as
`browser.assert.element(".foo")`.
See [Assertions](#assertions) for detailed discussion.
-#### `browser.console`
+#### browser.console
Provides access to the browser console (same as `window.console`).
-#### `browser.referer`
+#### browser.referer
You can use this to set the HTTP Referer header.
-#### `browser.resources`
+#### browser.resources
Access to history of retrieved resources. Also provides methods for retrieving
resources and managing the resource pipeline. When things are not going your
way, try calling `browser.resources.dump()`.
See [Resources](#resources) for detailed discussion.
-#### `browser.tabs`
+#### browser.tabs
Array of all open tabs (windows). Allows you to operate on more than one open
window at a time.
See [Tabs](#tabs) for detailed discussion.
-#### `browser.eventLoop`
-#### `browser.errors`
+#### browser.eventLoop
+#### browser.errors
### Extending The Browser
@@ -79,59 +79,58 @@ first tab would be the window with the document "/foo".
The following operations are used for managing tabs:
-#### `browser.close(window)`
+#### browser.close(window)
Closes the tab with the given window.
-#### `browser.close()`
+#### browser.close()
Closes the currently open tab.
-#### `browser.tabs`
+#### browser.tabs
Returns an array of all open tabs.
-#### `browser.tabs[number]`
+#### browser.tabs[number]
Returns the tab with that index number.
-#### `browser.tabs[string]`
-#### `browser.tabs.find(string)`
+#### browser.tabs[string]
+#### browser.tabs.find(string)
Returns the tab with that name.
-#### `browser.tabs.closeAll()`
+#### browser.tabs.closeAll()
Closes all tabs.
-#### `browser.tabs.current`
+#### browser.tabs.current
-Returns the currently active tab.
+This is a read/write property. It returns the currently active tab.
-#### `browser.tabs.current = window`
+Can also be used to change the currently active tabe. You can set it to a
+window (e.g. as currently returned from `browser.current`), a window name or the
+tab index number.
-Changes the currently active tab. You can set it to a window (e.g. as currently
-returned from `browser.current`), a window name or the tab index number.
-
-#### `browser.tabs.dump(output)`
+#### browser.tabs.dump(output)
Dump a list of all open tabs to standard output, or the output stream.
-#### `browser.tabs.index`
+#### browser.tabs.index
Returns the index of the currently active tab.
-#### `browser.tabs.length`
+#### browser.tabs.length
Returns the number of currently opened tabs.
-#### `browser.open(url: "http://example.com")`
+#### browser.open(url: "http://example.com")
Opens and returns a new tab. Supported options are:
- `name` - Window name.
- `url` - Load document from this URL.
-#### `browser.window`
+#### browser.window
Returns the currently active window, same as `browser.tabs.current.`
@@ -140,233 +139,292 @@ Returns the currently active window, same as `browser.tabs.current.`
## Assertions
-Node.js core includes an `assert` function, and there are many alternatives you
-can use for assertions and expectations. Obviously Zombie will support all of
-them.
-
-To make your life easier, it also introduces a set of convenience assertions you
-can execute directly against the browser object. For example, to check that a
-page load completed successfully, you may do:
-
+To make life easier, Zombie introduces a set of convenience assertions that you
+can access directly from the browser object. For example, to check that a page
+loaded successfuly:
browser.assert.success();
browser.assert.text("title", "My Awesome Site");
browser.assert.element("#main");
-Assertions that take an expected value, will compare that against the actual
-value. The expected value can be a primitive JavaScript value (string, number,
-etc), a regular expression or a function. In the later case, the function is
-called with the actual value, and the assertion passes if the function returns
-true.
+These assertions are available from the `browser` object since they operate on a
+particular browser instance -- generally dependent on the currently open window,
+or document loaded in that window.
+
+Many assertions require an element/elements as the first argument, for example,
+to compare the text content (`assert.text`), or attribute value
+(`assert.attribute`). You can pass one of the following values:
+
+- An HTML element or an array of HTML elements
+- A CSS selector string (e.g. "h2", ".book", "#first-name")
-Assertions that take a CSS selector use it to retrieve an HTML element or
-elements. You can also pass the element(s) directly instead of a selector (e.g.
-if you need to access an element inside an iframe).
+Many assertions take an expected value and compare it against the actual value.
+For example, `assert.text` compares the expected value against the text contents
+of one or more strings. The expected value can be one of:
+
+- A JavaScript primitive value (string, number)
+- `undefined` or `null` are used to assert the lack of value
+- A regular expression
+- A function that is called with the actual value and returns true if the
+ assertion is true
+- Any other object will be matched using `assert.deepEqual`
+
+Note that in some cases the DOM specification indicates that lack of value is an
+empty string, not `null`/`undefined`.
All assertions take an optional last argument that is the message to show if the
-assertion fails, but when using frameworks that has good reporting (e.g. Mocha)
-you want to let the assertion format the message for you.
+assertion fails. Better yet, use a testing framework like
+[Mocha](http://visionmedia.github.com/mocha/) that has good diff support and
+don't worry about these messages.
+
+
+### Available Assertions
The following assertions are available:
-#### `browser.assert.attribute(selector, name, expected, message)`
+#### assert.attribute(selection, name, expected, message)
-Assert the named attribute of the selected element(s) has the expected value.
-Fails if no elements found.
+Asserts the named attribute of the selected element(s) has the expected value.
-#### `browser.assert.className(selector, className, message)`
+Fails if no element found.
-Asserts that selected element(s) has the that and only that class name.
+#### assert.className(selection, className, message)
-#### `browser.assert.cookie(name, expected, message)`
+Asserts that selected element(s) has that and only that class name. May also be
+space-separated list of class names.
+
+Fails if no element found.
+
+#### assert.cookie(name, expected, message)
Asserts that a cookie with the given name has the expected value.
-#### `browser.assert.element(selector, message)`
+#### assert.element(selection, message)
+
+Asserts that one element matching selection exists.
+
+Fails if no element or more than one matching element are found.
-Assert that an element matching selector exists.
+#### assert.elements(selection, count, message)
-#### `browser.assert.elements(selector, count, message)`
+Asserts how many elements exist in the selection.
-Assert how many elements exist that match the selector.
+The argument `count` can be a number, or an object with the following
+properties:
-The count can be a number, or an object with the following properties:
+- `atLeast` - Expecting to find at least that many elements
+- `atMost` - Expecting to find at most that many elements
+- `exactly` - Expecting to find exactly that many elements
-- `atLeast` - Expect to find at least that many elements.
-- `atMost` - Expect to find at most that many elements.
-- `exactly` - Expect to find exactly that many elements.
+#### assert.evaluate(expression, expected, message)
-#### `browser.assert.evaluate(expression, expected, message)`
+Evaluates the JavaScript expression in the context of the currently open window.
-Evaluates the JavaScript expression in the browser context. With one argument,
-asserts that the value is true. With two or three arguments, asserts that the
-value of the expression matches the expected value.
+With one argument, asserts that the value is equal to `true`.
-#### `browser.assert.global(name, expected, message)`
+With two/three arguments, asserts that the returned value matches the expected
+value.
+
+#### assert.global(name, expected, message)
Asserts that the global (window) property has the expected value.
-#### `browser.assert.hasClass(selector, className, message)`
+#### assert.hasClass(selection, className, message)
-Asserts that selected element(s) has the expected class name (it may have many
-other class names).
+Asserts that selected element(s) have the expected class name. Elements may
+have other class names (unlike `assert.className`).
-#### `browser.assert.hasFocus(selector, message)`
+Fails if no element found.
+
+#### assert.hasFocus(selection, message)
Asserts that selected element has the focus.
-#### `browser.assert.input(selector, expected, message)`
+If the first argument is `null`, asserts that no element has the focus.
-Asserts that selected input field (text field, text area, etc) has the expected
-value.
+Otherwise, fails if element not found, or if more than one element found.
-#### `browser.assert.hasNoClass(selector, className, message)`
+#### assert.input(selection, expected, message)
-Asserts that selected element(s) does not have the expected class name (it may
-have many other class names).
+Asserts that selected input field(s) (`input`, `textarea`, `select` etc) have
+the expected value.
-#### `browser.assert.prompted(messageShown, message)`
+Fails if no element found.
-Assert that browser prompted with a given message.
+#### assert.hasNoClass(selection, className, message)
-#### `browser.assert.redirected(message)`
+Asserts that selected element(s) does not have the expected class name. Elements may
+have other class names (unlike `assert.className`).
-Asserts that browser was redirected when retrieving the current page.
+Fails if no element found.
-#### `browser.assert.success(message)`
+#### assert.prompted(messageShown, message)
-Assert that the last page load returned status code 200.
+Asserts the browser prompted with a given message.
-#### `browser.assert.status(code, message)`
+#### assert.redirected(message)
-Assert that the last page load returned the expected status code.
+Asserts the browser was redirected when retrieving the current page.
-#### `browser.assert.style(selector, style, expected, message)`
+#### assert.success(message)
-Assert that the style property of the selected element(s) the expected value.
+Asserts the current page loaded successfully (status code 2xx or 3xx).
-#### `browser.assert.text(selector, expected, message)`
+#### assert.status(code, message)
-Assert that text content of selected element(s) matche the expected value.
+Asserts the current page loaded with the expected status code.
-#### `browser.assert.url(url, message)`
+#### assert.style(selection, style, expected, message)
-Asserts that current page has the expected URL.
+Asserts that selected element(s) have the expected value for the named style
+property. For example:
-The expected URL value can be a string, regular expression, or function just
-like every other assertion. It can also be an object, in which case, individual
-properties are matched against the URL.
+ browser.assert.style(".navigation", "opacity", 0.5)
+
+Fails if no element found.
+
+#### assert.text(selection, expected, message)
+
+Asserts that selected element(s) have the expected text content. For example:
+
+ browser.assert.text("title", "My Awesome Page")
+
+Fails if no element found.
+
+#### assert.url(url, message)
+
+Asserts the current page has the expected URL.
+
+The expected URL can be one of:
+
+- The full URL as a string
+- A regular expression
+- A function, called with the URL and returns true if the assertion is true
+- An object, in which case individual properties are matched against the URL
For example:
- browser.assert.url({ pathame: "/resource" });
+ browser.assert.url("http://localhost/foo/bar")
+ browser.assert.url({ pathame: "/foo/bar" });
browser.assert.url({ query: { name: "joedoe" } });
-### Add Your Own Assertions
-You can add more assertions by adding methods to the prototype of
-`Browser.Assert`. These have access to the browser as a property, for example:
+### Roll Your Own Assertions
+
+Not seeing an assertion you want? You can add your own assertions to the
+prototype of `Browser.Assert`.
+
+For example:
// Asserts the browser has the expected number of open tabs.
Browser.Assert.prototype.openTabs = function(expected, message) {
assert.equal(this.browser.tabs.length, expected, message);
};
+Or application specific:
+
+
+ // Asserts which links is highlighted in the navigation bar
+ Browser.Assert.navigationOn = function(linkText) {
+ this.assert.element(".navigation-bar");
+ this.assert.text(".navigation-bar a.highlighted", linkText);
+ };
+
## Events
-#### `console (level, messsage)`
+#### console (level, messsage)
Emitted whenever a message is printed to the console (`console.log`,
`console.error`, `console.trace`, etc).
The first argument is the logging level, one of `debug`, `error`, `info`, `log`,
`trace` or `warn`. The second argument is the message to log.
-#### `active (window)`
+#### active (window)
Emitted when this window becomes the active window.
-#### `closed (window)`
+#### closed (window)
Emitted when a window is closed.
-#### `done ()`
+#### done ()
Emitted whenever the event loop is empty.
-#### `evaluated (code, result, filename)`
+#### evaluated (code, result, filename)
Emitted whenever JavaScript code is evaluated. The first argument is the
JavaScript function or source code, the second argument the result, and the
third argument is the filename.
-#### `event (event, target)`
+#### event (event, target)
Emitted whenever a DOM event is fired on the target element, document or window.
-#### `focus (element)`
+#### focus (element)
Emitted whenever an input element receives the focus.
-#### `inactive (window)`
+#### inactive (window)
Emitted when this window is no longer the active window.
-#### `interval (function, interval)`
+#### interval (function, interval)
Emitted whenever an interval event (`setInterval`) is fired, with the function and
interval.
-#### `link (url, target)`
+#### link (url, target)
Emitted when a link is clicked and the browser navigates to a new URL. Includes
the URL and the target window (default to `_self`).
-#### `loaded (document)`
+#### loaded (document)
Emitted when a document is loaded into a window or frame. This event is emitted
after the HTML is parsed and loaded into the Document object.
-#### `loading (document)`
+#### loading (document)
Emitted when a document is loaded into a window or frame. This event is emitted
with an empty Document object, before parsing the HTML response.
-#### `opened (window)`
+#### opened (window)
Emitted when a window is opened.
-#### `redirect (request, response)`
+#### redirect (request, response)
Emitted when following a redirect.
The first argument is the request, the second argument is the redirect response.
The URL of the new resource to retrieve is given by `response.url`.
-#### `request (request, target)`
+#### request (request, target)
Emitted before making a request to retrieve the resource.
The first argument is the request object (see *Resources* for more details), the
second argument is the target element/document.
-#### `response (request, response, target)`
+#### response (request, response, target)
Emitted after receiving the response when retrieving a resource.
The first argument is the request object (see *Resources* for more details), the
second argument is the response that is passed back, and the third argument is
the target element/document.
-#### `submit (url, target)`
+#### submit (url, target)
Emitted when a form is submitted. Includes the action URL and the target window
(default to `_self`).
-#### `timeout (function, delay)`
+#### timeout (function, delay)
Emitted whenever a timeout event (`setTimeout`) is fired, with the function and
delay.
View
25 doc/new/generate.coffee → doc/new/scripts/generate.coffee
@@ -1,11 +1,24 @@
#!/usr/bin/env coffee
+#
+# Generates Web page (index.html), PDF (zombie.pdf) and Kindle Mobile
+# (zombie.mobi).
+#
+# You'll need Markdown to generate all three:
+#
+# brew install markdown
+#
+# WkHTMLtoPDF to generate the PDF:
+#
+# brew install wkhtmltopdf
+#
+# And kindlegen available for download from Amazon.
{ execFile } = require("child_process")
File = require("fs")
console.log "Generating index.html ..."
-layout = File.readFileSync("style/layout.html").toString()
-execFile "markdown", ["README.md"], (error, stdout, stderr)->
+layout = File.readFileSync("#{__dirname}/../style/layout.html").toString()
+execFile "markdown", ["#{__dirname}/../README.md"], (error, stdout, stderr)->
if error
console.error("Note: if you haven't already, brew install markdown")
console.error(error.message)
@@ -18,7 +31,7 @@ execFile "markdown", ["README.md"], (error, stdout, stderr)->
content = stdout.replace(/<h([1-3])>(.*)<\/h[1-3]>/g, addIDToHeader)
html = layout.replace("{content}", content)
- File.writeFileSync("index.html", html)
+ File.writeFileSync("#{__dirname}/../index.html", html)
console.log "Generating zombie.pdf ..."
pdfOptions = [
@@ -28,8 +41,8 @@ execFile "markdown", ["README.md"], (error, stdout, stderr)->
"--title", "Zombie.js",
"--allow", "images",
"--footer-center", "Page [page]",
- "index.html",
- "zombie.pdf"
+ "#{__dirname}/../index.html",
+ "#{__dirname}/../zombie.pdf"
]
execFile "wkhtmltopdf", pdfOptions, (error, stdout, stderr)->
if error
@@ -39,7 +52,7 @@ execFile "markdown", ["README.md"], (error, stdout, stderr)->
console.log "Generating zombie.mobi ..."
kindleOptions = [
"-c2"
- "index.html",
+ "#{__dirname}/../index.html",
"-o", "zombie.mobi"
]
execFile "kindlegen", kindleOptions, (error, stdout, stderr)->
View
6 doc/new/server.coffee → doc/new/scripts/server.coffee
@@ -6,8 +6,8 @@ File = require("fs")
server = Express()
server.get "/", (req, res)->
- layout = File.readFileSync("style/layout.html").toString()
- execFile "markdown", ["README.md"], {}, (error, stdout, stderr)->
+ layout = File.readFileSync("#{__dirname}/../style/layout.html").toString()
+ execFile "markdown", ["#{__dirname}/../README.md"], {}, (error, stdout, stderr)->
if error
res.send(500, error.message)
else
@@ -16,7 +16,7 @@ server.get "/", (req, res)->
server.get "/*", (req, res)->
try
- File.createReadStream("#{req.params[0]}")
+ File.createReadStream("#{__dirname}/../#{req.params[0]}")
.on "error", (error)->
res.send(404, error.message)
.pipe(res)
View
9 doc/new/style/zombie.css
@@ -1,7 +1,7 @@
/** General content styles **/
body {
- font-family: "Helvetica Neue", "Helvetica", "Verdana";
+ font-family: "Helvetica Neue", "Calibri", "Helvetica", "Verdana";
font-size: 13pt;
line-height: 1.3;
color: #222;
@@ -13,7 +13,7 @@ h1 {
font-size: 300%;
margin: 0 0 0.6em 0;
}
-h1, h2, h2, h4 {
+h1, h2, h3, h4 {
font-family: "Optima", "Helvetica", "Trebuchet MS";
color: steelblue;
font-weight: 700;
@@ -36,6 +36,9 @@ pre {
background: #eef;
padding: 0.6em;
}
+h4 code {
+ color: steelblue;
+}
a {
color: steelblue;
text-decoration: none;
@@ -204,6 +207,8 @@ strong {
@media print {
body {
margin: 0.75in 0.5in 1.25in 0.5in;
+ color: #000;
+ font-family: "Garamond";
}
.content {
padding: 0 !important;

0 comments on commit cb186f6

Please sign in to comment.