search

velesin / jasmine-jquery

jQuery matchers and fixture loader for Jasmine framework
MIT License
1.89k stars 346 forks source link

readme

!!! IMPORTANT: WE NEED A NEW MAINTAINER !!!

Neither me (the original lib author) nor Travis (the current lib maintainer) can maintain this library any longer as actively as the GREAT community around it deserves.

So, we're looking for a new maintainer for this lib - if you're interested, ping me on Twitter or through a comment in this GitHub issue.

jasmine-jquery Build Status

jasmine-jquery provides two extensions for the Jasmine JavaScript Testing Framework:

Installation

Choose one of the following options:

jQuery matchers

jasmine-jquery provides the following custom matchers (in alphabetical order):

The same as with standard Jasmine matchers, all of the above custom matchers may be inverted by using .not prefix, e.g.:

expect($('<div>some text</div>')).not.toHaveText(/other/)

HTML Fixtures

The Fixture module of jasmine-jquery allows you to load HTML content to be used by your tests. The overall workflow is as follows:

In myfixture.html file:

<div id="my-fixture">some complex content here</div>

Inside your test:

loadFixtures('myfixture.html')
$('#my-fixture').myTestedPlugin()
expect($('#my-fixture')).to...

By default, fixtures are loaded from spec/javascripts/fixtures. You can configure this path: jasmine.getFixtures().fixturesPath = 'my/new/path';.

Note: If you are running your test with Karma, remember that your files are served from a base/ directory, so your path should be configured to: jasmine.getFixtures().fixturesPath = 'base/my/new/path';.

Your fixture is being loaded into the <div id="jasmine-fixtures"></div> container that is automatically added to the DOM by the Fixture module (If you REALLY must change the id of this container, try: jasmine.getFixtures().containerId = 'my-new-id'; in your test runner). To make tests fully independent, fixtures container is automatically cleaned-up between tests, so you don't have to worry about left-overs from fixtures loaded in preceeding test. Also, fixtures are internally cached by the Fixture module, so you can load the same fixture file in several tests without penalty to your test suite's speed.

To invoke fixture related methods, obtain Fixtures singleton through a factory and invoke a method on it:

jasmine.getFixtures().load(...)

There are also global shortcut functions available for the most used methods, so the above example can be rewritten to just:

loadFixtures(...)

Several methods for loading fixtures are provided:

All of above methods have matching global shortcuts:

var fixture = setFixtures('<div class="post">foo</div>')
var post = fixture.find('.post')

Also, a helper method for creating HTML elements for your tests is provided:

It creates an empty DIV element with a default id="sandbox". If a hash of attributes is provided, they will be set for this DIV tag. If a hash of attributes contains id attribute it will override the default value. Custom attributes can also be set. So e.g.:

sandbox()

Will return:

<div id="sandbox"></div>

And:

sandbox({
  id: 'my-id',
  class: 'my-class',
  myattr: 'my-attr'
})

Will return:

<div id="my-id" class="my-class" myattr="my-attr"></div>

Sandbox method is useful if you want to quickly create simple fixtures in your tests without polluting them with HTML strings:

setFixtures(sandbox({class: 'my-class'}))
$('#sandbox').myTestedClassRemoverPlugin()
expect($('#sandbox')).not.toHaveClass('my-class')

This method also has a global shortcut available:

Additionally, two clean up methods are provided:

These two methods do not have global shortcut functions.

Style Fixtures

The StyleFixtures module is pretty much like the Fixtures module, but it allows you to load CSS content on the page while testing. It may be useful if your tests expect that certain css rules are applied to elements that you are testing. The overall workflow is typically the same:

In mycssfixture.css file:

.elem { position: absolute }

Inside your test:

loadStyleFixtures('mycssfixture.css')
$('#my-fixture').myTestedPlugin()
expect($('#my-fixture .elem')).toHaveCss({left: "300px"})

Notice that if you haven't applied the position: absolute rule to the .elem and try to test its left position in some browsers (e.g. GoogleChrome) you will allways get the value auto even if your plugin did everything correct and applied positioning. So that's why you might need to load style fixtures. In Firefox though you will get the correct value even without the position: absolute.

By default, style fixtures are loaded from spec/javascripts/fixtures. You can configure this path: jasmine.getStyleFixtures().fixturesPath = 'my/new/path';.

Like in Fixtures module, StyleFixtures are also automatically cleaned-up between tests and are internally cached, so you can load the same fixture file in several tests without penalty to your test suite's speed.

To invoke fixture related methods, obtain StyleFixtures singleton through a factory and invoke a method on it:

jasmine.getStyleFixtures().load(...)

There are also global shortcut functions available for the most used methods, so the above example can be rewritten to just:

loadStyleFixtures(...)

Several methods for loading fixtures are provided:

All of above methods have matching global shortcuts:

Additionally, two clean up methods are provided:

These two methods do not have global shortcut functions.

JSON Fixtures

The JSONFixtures modules allows you to load JSON data from file (instead of putting huge blocks of data in the spec files).

In myjsonfixture.json file:

{"property1":"value1", "array1":[1,2,3]}

Inside your test:

var data = getJSONFixture('myjsonfixture.json')
// or load and get the JSON two-step
var fixtures = loadJSONFixtures('myjsonfixture.json')
var data = fixtures['myjsonfixture.json']

expect(myDataManipulator.processData(test_data)).to...)

By default, fixtures are loaded from spec/javascripts/fixtures/json. You can configure this path: jasmine.getJSONFixtures().fixturesPath = 'my/new/path';.

Your fixture data is loaded into an object stashed by the JSONFixtures structure. You fetch the data using the filename as the key. This allows you to load multiple chunks of test data in a spec.

Because a deep copy of Javascript objects can be a little tricky, this module will refetch data each time you call load. If you modify the data within a spec, you must call load or loadJSONFixtures again to repopulate the data.

To invoke fixture related methods, obtain Fixtures singleton through a factory and invoke a method on it:

jasmine.getJSONFixtures().load(...)

There are also global shortcut functions available for the most used methods, so the above example can be rewritten to just:

loadJSONFixtures(...)

Several methods for loading fixtures are provided:

All of above methods have matching global shortcuts:

Event Spies

Spying on jQuery events can be done with spyOnEvent and expect(eventName).toHaveBeenTriggeredOn(selector) or expect(spyEvent).toHaveBeenTriggered() . First, spy on the event:

var spyEvent = spyOnEvent('#some_element', 'click')
$('#some_element').click()
expect('click').toHaveBeenTriggeredOn('#some_element')
expect(spyEvent).toHaveBeenTriggered()

You can reset spy events

var spyEvent = spyOnEvent('#some_element', 'click')
$('#some_element').click()
expect('click').toHaveBeenTriggeredOn('#some_element')
expect(spyEvent).toHaveBeenTriggered()
// reset spy events
spyEvent.reset()
expect('click').not.toHaveBeenTriggeredOn('#some_element')
expect(spyEvent).not.toHaveBeenTriggered()

You can similarly check if triggered event was prevented:

var spyEvent = spyOnEvent('#some_element', 'click')
$('#some_element').click(function (event){event.preventDefault();})
$('#some_element').click()
expect('click').toHaveBeenPreventedOn('#some_element')
expect(spyEvent).toHaveBeenPrevented()

You can also check if the triggered event was stopped:

var spyEvent = spyOnEvent('#some_element', 'click')
$('#some_element').click(function (event){event.stopPropagation();})
$('#some_element').click()
expect('click').toHaveBeenStoppedOn('#some_element')
expect(spyEvent).toHaveBeenStopped()

Many thanks to Luiz Fernando Ribeiro for his article on Jasmine event spies.

Dependencies

jasmine-jquery v2.0.0+ is to be used with jasmine v2.0.0+. jasmine-jquery v1.7.0 is to be used with jasmine < v2.0.0.

jasmine-jquery is tested with jQuery 2.0 on IE, FF, Chrome, and Safari. There is a high chance it will work with older versions and other browsers as well, but I don't typically run test suite against them when adding new features.

Cross domain policy problems under Chrome

Newer versions of Chrome don't allow file:// URIs read other file:// URIs. In effect, jasmine-jquery cannot properly load fixtures under some versions of Chrome. An override for this is to run Chrome with a switch --allow-file-access-from-files. (https://github.com/velesin/jasmine-jquery/issues/4). Quit open Chromes before running Chrome with that switch. (https://github.com/velesin/jasmine-jquery/issues/179).

Under Windows 7, you have to launch C:\Users\[UserName]\AppData\Local\Google\Chrome[ SxS]\Application\chrome.exe --allow-file-access-from-files

Mocking with jasmine-ajax

jasmine-ajax library doesn't let user to manually start / stop XMLHttpRequest mocking, but instead it overrides XMLHttpRequest automatically when loaded. This breaks jasmine-jquery fixtures as fixture loading mechanism uses jQuery.ajax, that stops to function the very moment jasmine-ajax is loaded. A workaround for this may be to invoke jasmine-jquery preloadFixtures function (specifying all required fixtures) before jasmine-ajax is loaded. This way subsequent calls to loadFixtures or readFixtures methods will get fixtures content from cache, without need to use jQuery.ajax and thus will work correctly even after jasmine-ajax is loaded.

Testing with Javascript Test Driver

When using jstd and the jasmine adapter you will need to include jasmine-jquery.js after your jasmine-jstd-adapter files, otherwise jasmine-jquery matchers will not be available when tests are executed. Check out this issue for a thorough configuration example too.

Maintainer

Travis Jeffery: Twitter, GitHub.

Contributing