browser.coffee

Browser options you can set when creating new browser, or on browser instance.

Global options you can set on Browser and will be inherited by each new browser.

Use the browser to open up new windows and load documents.

The browser maintains state for cookies and localStorage.

Make sure we don't blow up Node when we get a JS error, but dump error to console. Also, catch any errors reported while processing resources/JavaScript.

Default (not global) options

Send this referer.

You can set the browser window.name property

Sets the browser options.

Returns all errors reported while loading this window.

Global options

True to have Zombie report what it's doing.

Which parser to use (HTML5 by default). For example: Browser.htmlParser = require("html5").HTML5 // HTML5, forgiving Browser.htmlParser = require("htmlparser") // Faster, stricter

True to load external stylesheets.

Maximum time to wait (visit, wait, etc).

Proxy URL.

Example Browser.proxy = "http://myproxy:8080" browser.visit("site", function(error, browser) { })

Run scripts included in or loaded from the page. Defaults to true.

If true, supress console.log output from scripts.

User agent string sent to server.

You can use visit with a path, and it will make a request relative to this host/URL.

Tells wait and any function that uses wait how long to wait for, executing timers. Defaults to 0.5 seconds.

Additional headers to be sent with each HTTP request

Changes the browser options, and calls the function with a callback (reset). When you're done processing, call the reset function to bring options back to their previous values.

See visit if you want to see this method in action.

Return a new browser with a snapshot of this browser's state. Any changes to the forked browser's state do not affect this browser.

Windows

Returns the currently open window

Open new browser window. Options are undocumented, use at your own peril.

browser.error => Error

Returns the last error reported while loading this window.

Events

Waits for the browser to complete loading resources and processing JavaScript events.

You can pass a callback as the last argument. Without a callback, this method returns a promise.

With duration as the first argument, this method waits for the specified time (in milliseconds) and any resource/JavaScript to complete processing. Duration can also be a function, called after each event to determine whether or not to proceed.

Without duration, Zombie makes best judgement by waiting up to 5 seconds for the page to load resources (scripts, XHR requests, iframes), process DOM events, and fire timeouts events.

Fire a DOM event. You can use this to simulate a DOM event, e.g. clicking a link. These events will bubble up and can be cancelled. Like wait this method either takes a callback or returns a promise.

name - Even name (e.g click) target - Target element (e.g a link) callback - Wait for events to be processed, then call me (optional)

Dispatch asynchronously. Returns true if preventDefault was set.

Accessors

browser.queryAll(selector, context?) => Array

Evaluates the CSS selector against the document (or context node) and return array of nodes. (Unlike document.querySelectorAll that returns a node list).

browser.query(selector, context?) => Element

Evaluates the CSS selector against the document (or context node) and return an element.

browser.querySelector(selector) => Element

Select a single element (first match) and return it.

selector - CSS selector

Returns an Element or null

browser.querySelectorAll(selector) => NodeList

Select multiple elements and return a static node list.

selector - CSS selector

Returns a NodeList or null

browser.text(selector, context?) => String

Returns the text contents of the selected elements.

selector - CSS selector (if missing, entire document) context - Context element (if missing, uses document)

Returns a string

browser.html(selector?, context?) => String

Returns the HTML contents of the selected elements.

selector - CSS selector (if missing, entire document) context - Context element (if missing, uses document)

Returns a string

Deprecated please use queryAll instead.

browser.xpath(expression, context?) => XPathResult

Evaluates the XPath expression against the document (or context node) and return the XPath result. Shortcut for document.evaluate.

browser.document => Document

Returns the main window's document. Only valid after opening a document (see browser.open).

browser.body => Element

Returns the body Element of the current document.

browser.statusCode => Number

Returns the status code of the request for loading the window.

browser.success => Boolean

True if the status code is 2xx.

browser.redirected => Boolean

Returns true if the request for loading the window followed a redirect.

source => String

Returns the unmodified source of the document loaded by the browser

close

Close all windows, dispose of all resources. You want to call this if you're running out of memory.

Navigation

browser.visit(url, callback?)

browser.visit(url, options, callback)

Loads document from the specified URL, processes events and calls the callback. If the second argument are options, uses these options for the duration of the request and resets the options afterwards.

The callback is called with null, the browser, status code and array of resource/JavaScript errors.

browser.load(html, callback)

Loads the HTML, processes events and calls the callback.

Without a callback, returns a promise.

Find (first of any) errors caught during document.write

Call callback or resolve promise

Otherwise wait for all events to process, wait handles errors

browser.location => Location

Return the location of the current document (same as window.location).

browser.location = url

Changes document location, loads new document if necessary (same as setting window.location).

browser.link(selector) : Element

Finds and returns a link by its text content or selector.

If the link has already been queried, return itself

browser.clickLink(selector, callback)

Clicks on a link. Clicking on a link can trigger other events, load new page, etc: use a callback to be notified of completion. Finds link by text content or selector.

selector - CSS selector or link text callback - Called with two arguments: error and browser

Return the history object.

Navigate back in history.

Reloads current page.

Returns a new Credentials object for the specified host. These authentication credentials will only apply when making requests to that particular host (hostname:port).

You can also set default credentials by using the host '*'.

If you need to get the credentials without setting them, call with true as the second argument.

Legacy support, remove in the future.

browser.saveHistory() => String

Save history to a text string. You can use this to load the data later on using browser.loadHistory.

browser.loadHistory(String)

Load history from a text string (e.g. previously created using browser.saveHistory.

Forms

browser.field(selector) : Element

Find and return an input field (INPUT, TEXTAREA or SELECT) based on a CSS selector, field name (its name attribute) or the text value of a label associated with that field (case sensitive, but ignores leading/trailing spaces).

If the field has already been queried, return itself

Try more specific selector first.

Use field name (case sensitive).

Try finding field from label.

Label can either reference field or enclose it

browser.fill(selector, value, callback) => this

Fill in a field: input field or text area.

selector - CSS selector, field name or text of the field label value - Field value

Without callback, returns this.

browser.check(selector, callback) => this

Checks a checkbox.

selector - CSS selector, field name or text of the field label

Without callback, returns this.

browser.uncheck(selector, callback) => this

Unchecks a checkbox.

selector - CSS selector, field name or text of the field label

Without callback, returns this.

browser.choose(selector, callback) => this

Selects a radio box option.

selector - CSS selector, field value or text of the field label

Returns this.

browser.select(selector, value, callback) => this

Selects an option.

selector - CSS selector, field name or text of the field label value - Value (or label) or option to select

Without callback, returns this.

browser.selectOption(option, callback) => this

Selects an option.

option - option to select

Without callback, returns this.

browser.unselect(selector, value, callback) => this

Unselects an option.

selector - CSS selector, field name or text of the field label value - Value (or label) or option to unselect

Without callback, returns this.

browser.unselectOption(option, callback) => this

Unselects an option.

option - option to unselect

Without callback, returns this.

browser.attach(selector, filename, callback) => this

Attaches a file to the specified input field. The second argument is the file name.

Without callback, returns this.

browser.button(selector) : Element

Finds a button using CSS selector, button name or button text (BUTTON or INPUT element).

selector - CSS selector, button name or text of BUTTON element

If the button has already been queried, return itself

browser.pressButton(selector, callback)

Press a button (button element or input of type submit). Typically this will submit the form. Use the callback to wait for the from submission, page to load and all events run their course.

selector - CSS selector, button name or text of BUTTON element callback - Called with two arguments: null and browser

browser.focused => element

Returns the element in focus.

Cookies and storage

Returns all the cookies for this domain/path. Domain defaults to hostname of currently open page. Path defaults to "/".

Save cookies to a text string. You can use this to load them back later on using browser.loadCookies.

Load cookies from a text string (e.g. previously created using browser.saveCookies.

Returns local Storage based on the document origin (hostname/port). This is the same storage area you can access from any document of that origin.

Returns session Storage based on the document origin (hostname/port). This is the same storage area you can access from any document of that origin.

Save local/session storage to a text string. You can use this to load the data later on using browser.loadStorage.

Load local/session stroage from a text string (e.g. previously created using browser.saveStorage.

Scripts

Evaluates a JavaScript expression in the context of the current window and returns the result. When evaluating external script, also include filename.

You can also use this to evaluate a function in the context of the window: for timers and asynchronous callbacks (e.g. XHR).

Interaction

browser.onalert(fn)

Called by window.alert with the message.

browser.onconfirm(question, response)

browser.onconfirm(fn)

The first form specifies a canned response to return when window.confirm is called with that question. The second form will call the function with the question and use the respone of the first function to return a value (true or false).

The response to the question can be true or false, so all canned responses are converted to either value. If no response available, returns false.

browser.onprompt(message, response)

browser.onprompt(fn)

The first form specifies a canned response to return when window.prompt is called with that message. The second form will call the function with the message and default value and use the response of the first function to return a value or false.

The response to a prompt can be any value (converted to a string), false to indicate the user cancelled the prompt (returning null), or nothing to have the prompt return the default value or an empty string.

browser.prompted(message) => boolean

Returns true if user was prompted with that message (window.alert, window.confirm or window.prompt)

Debugging

browser.viewInBrowser(name?)

Views the current document in a real Web browser. Uses the default system browser on OS X, BSD and Linux. Probably errors on Windows.

browser.lastRequest => HTTPRequest

Returns the last request sent by this browser. The object will have the properties url, method, headers, and body.

browser.lastResponse => HTTPResponse

Returns the last response received by this browser. The object will have the properties url, status, headers and body. Long bodies may be truncated.

browser.lastError => Object

Returns the last error received by this browser in lieu of response.

Zombie can spit out messages to help you figure out what's going on as your code executes.

To spit a message to the console when running in debug mode, call this method with one or more values (same as console.log). You can also call it with a function that will be evaluated only when running in debug mode.

For example: browser.log("Opening page:", url); browser.log(function() { return "Opening page: " + url });

Dump information to the consolt: Zombie version, current URL, history, cookies, event loop, etc. Useful for debugging and submitting error reports.

Represents credentials for a given host.

Apply security credentials to the outgoing request headers.

Use HTTP Basic authentication. Requires two arguments, username and password.

Use OAuth 2.0 Bearer (recent drafts). Requires one argument, the access token.

Use OAuth 2.0 (early drafts). Requires one argument, the access token.

Reset these credentials.