Jasmine Helpers
Collection of small JavaScript helpers. These are intended to be used with JavaScript testing framework Jasmine.
How to use
The easiest way to add these helpers to your project is to use Bower:
bower install jasmine-helpers
Then point to these helpers in your Jasmine runner. For example:
<script src="bower_components/jasmine-helpers/helpers/simulate-event.js"></script>
If you are using Grunt to run your Jasmine tests automatically (I highly recommend it), add the path to helpers in the configuration, like this:
grunt.initConfig({
jasmine: {
pivotal: {
src: '...',
options: {
specs: '...',
helpers: 'bower_components/jasmine-helpers/helpers/*.js'
}
}
}
});
Documentation
- CSS
- Elements
- Events
getCssProperty
getCssProperty(elment, property_name);
Returns computed value of CSS property for given element. Event the default values for undefined properties (e.g. block
for display
property in DIV).
The results are normalised. So asking for any size properties (e.g. width
) will always return value in pixels, colors will be returned in rgb(...)
format, etc. See examples below.
Parameters
element
Reference to the element from which you'd like to retrieve value of CSS property.
property_name
Name of the CSS property.
Examples
<div id="myElement" style="width: 100px; background: red;"></div>
Get value of undefined property:
getCssProperty(my_element, 'display'); // block
Get value of defined property:
getCssProperty(my_element, 'width'); // 100px
Get value of normalized property:
getCssProperty(my_element, 'background-color'); // rgb(255, 0, 0)
isVisible
isVisible(element);
Checks if element is present in the document and is visible. It will return false
if:
- Element does not exist.
- Element exists, but is not inserted in the document.
- Element is hidden via CSS by either
display: none
orvisibility: hidden
.
Parameters
element
Element which you'd like to check for visibility.
Examples
isVisible(my_element); // true
my_element.style.display = 'none';
isVisible(my_element); // false
createPositionedElement
createPositionedElement(left, top, css_attributes);
Creates absolutely positioned DIV element and returns it. It does not insert it to the document (that's what insertPositionedElement()
is for).
By default the size of the element is 100*100px. You can change this (and any other CSS attribute) via the third parameter.
Parameters
left (default 100
)
top (default 100
)
Left and top position of the element.
css_attributes Object with CSS attributes and their values. All these will be set to element
Examples
Returns absolutely positioned DIV element at position 0,0 and size 100*100px:
var my_element = createPositionedElement();
Returns element positioned at 100,200:
var my_element = createPositionedElement(100, 200);
Returns red element:
var my_element = createPositionedElement(null, null, {background: 'red'});
insertPositionedElement
insertPositionedElement(left, top, parent_node, css_attributes);
This is basicaly the same as [createPositionedElement()
], but it also inserts the created element to the document (or any other DOM node).
Parameters
left (default 100
)
top (default 100
)
Left and top position of the element.
parent_node (default document.body
)
DOM node into which created element should be inserted. This allows you to easily create nested DOM structures.
css_attributes
Object with CSS attributes and their values. All these will be set to element
Examples
Insert new positioned element with default position to the BODY:
var my_element = insertPositionedElement()
Nest one element into another:
var outer_element = insertPositionedElement();
outer_element.parentNode; // document.body
var inner_element = insertPositionedElement(null, null, outer_element);
inner_element.parentNode; // outer_element
NOTE regarding positioned elements
All positioned elements created using createPositionedElement()
or insertPositionedElement()
have classname created-positioned-element
. This is handy when you need to cleanup all created elements during your tests:
describe('my tests', function () {
afterEach(function () {
// find all created elements inserted to the document...
var elements = document.querySelectorAll('.created-positioned-element');
// ...and remove them
for (var i = 0; i < elements.length; i++) {
elements[i].parentNode.removeChild(elements[i]);
}
});
it('test that inserts elements', function () {
// ...
})
});
simulateEvent
simulateEvent(object, event_type)
This is handy if you want to test events that are otherwise hard to fire.
For example window.onscroll
does not fire if you call window.scrollTo()
or window.scrollBy()
methods. If you need to test interactions when user scrolls the content, you will need to fire the event manually.
NOTE: Be careful when manually firing window.onload
event. Every onload listener will be activated, not just the one you want to test. Which can have funny effects on your testing environment.
Parameters
object
Object that should fire the element. E.g. window
.
event_type
Any event name that can be fired. E.g. scroll
.
Examples
Fire the window.onscroll
event after you scroll the viewport:
window.scrollBy(0, 100);
simulateEvent(window, 'scroll');
simulateMouseEvent
simulateMouseEvent(object, event_type, button, properties)
Simulates any mouse event. This is very handy when testing user interactions with the UI. Event object allows you to set lots of various properties, but most of the time, you just care about two of them: event type (usualy click
) and mouse button (usualy left
).
Parameters
object
Which DOM object should receive the event. This should be a reference to an element or document.body
.
event_type (default click
)
This is a list of valid values you can use: click
, mousedown
, mouseup
, mouseover
, mousemove
and mouseout
.
button (default left
)
Default value is left
. This represents a mouse button that triggers the event. Valid values are: left
, right
and middle
.
properties
Object with event properties. You will probably only need this in special cases. For example when you need to specify exact coordinates of the mouse at the time of event. See complete list of event properties at MDN.
Examples
Left-click on the element:
simulateMouseEvent(my_element);
Left mouse button pressed on the element:
simulateMouseEvent(my_element, 'mousedown');
Right mouse button pressed on the element:
simulateMouseEvent(my_element, 'mousedown', 'right');
Right mouse button pressed on the element at coordinates x: 100px, y: 100px
:
simulateMouseEvent(my_element, 'mousedown', 'right', {
clientX: 100, clientY: 100
});
How to contribute
TODO
Bug reports, feature requests and contact
If you found any bugs, if you have feature requests or any questions, please, either file an issue at GitHub or send me an e-mail at riki@fczbkk.com.
License
JS Helpers is published under the UNLICENSE license. Feel free to use it in any way.