A node module for validating site analytics
This is node application for executing and validating analytic events.
Haunted is available from npm.
$ npm install haunted
To use Haunted, just instantiate a new Haunted object, passing it a definition, suite describer, and suite tester, and call run().
Haunted = require'haunted';haunted = definition describer tester;hauntedrun;
The definition argument should be an object configuring your analytics definition, see configuration.
The describer argument should be a function which, when called, creates a test suite for a particular page. It is passed 3 arguments:
page: an object representing the page currently being tested
setup(done): a function which, when called, sets up the test suite (by loading the page in a headless browser); it's argument is a function to be called when the setup is done
suite(this): a function which, when called, executes the test suite; it's argument should be the test context.
For example, this is a simple describer function:
The tester argument should be a function which, when called, actually tests an expectation. It's one argument is an object with three properties:
expectation.name: the name of the expectation (ex. the URL of a resource which was expected)
expectation.occurred: the number of instances which actually occurred
expectation.expected: the number of instances which was expected
For example, here is a simple tester which outputs to the console:
if expectationoccurred != expectationexpectedconsole.logutilformat'%s expected %d, received %d on %s' expectationname expectationexpected expectationoccurred expectationpageurl;elseconsole.logutilformat'passed %s on %s' expectationname expectationpageurl;
Two examples are included, a simple one using console.log and an example using the Mocha test framework. To run the simple example, just execute this command:
To use the Mocha example, you must install the mocha npm module.
npm install -g mochanpm install should
To run the Mocha example, just use this command:
mocha --reporter spec --ui bdd -r should example/mocha.js
var definition = require'./definition.json';
The base URL of your site. Ex.
If your site is behind basic HTTP authentication, you can pass a username and password in your definition file to enable authentication.
"authentication":"username": "YOURUSERNAMEHERE""password": "YOURPASSWORDHERE"
This contains configuration information which is passed to the datastore.
An object of all queries which your pages would like to check. The key is the query name and the value is an object containing query properties which are passed along to the datastore.
"queries":"page.hour":"collection": "analytics.page.hour""query": "name": "<%= relative %>" "date": "<%= hour %>""field": "n""sort": "date": -1
The collection this query should reference.
The actual query parameters to be passed. This format will often depend on the driver. Note that in field names certain properties will be replaced:
<%= relative %>becomes the relative URL of the current page.
The name of the field, in the fetched document, where the changing value can be found.
An object parameter to pass for sorting the collection query, useful in the MongoDB datastore.
The number of milliseconds to wait before final (post-visit) check of datastore. Useful if you have delayed writes.
In Haunted, a set is an array of URLs which are expected. You can define multiple sets (each of which has multiple URLs), and each page can reference multiple sets. Note that URLs will be naively partially matched, such that if a requested resource contains one of these URLs as a substring, it will be considered a match. For example:
The pages property contains an array of pages to be checked, each of which has a number of properties. Ex.
"pages":"uri": "/the-7-awesome-types-of-slideshows-2010-11""sets":"google": 1"internal": 2"actions":"click": "a.sl-start""queries":"page.hour": 1
The location of the page, relative to the base url. Ex.
An object containing the sets, as defined elsewhere in your definition, which this page should load. The key is the set and the value is the number of times it should be referenced. The above example will expect each URL in
internal set twice:
An array containing any actions to take on the page. Each action is represented as an object with the key being the event/action and the value being the target. Currently only the
click ation is supported.
An object containing the queries, as defined elsewhere in your definition, which this page should check. The key is the query and the value is the amount we expect that query to be updated by.
Haunted supports tracking that values are properly incremented in your datastore for analytics calls. To use a datastore, you must define storage and queries in your configuration, and activate the datastore. Currently only a MongoDB datastore driver is included with Haunted, which can be activated thusly:
haunted = definition describer tester;// use the mongo datastorehauntedsetStoragehauntedMongoHouse;
As the datastore is a simple class, you can easily write drivers for other datastores by following the conventions of the mongo datastore. If you do so, please submit a pull request so we can include it!