jasmine-dom-custom-matchers
work?A custom matchers syntax has changed with the release of jasmine 2.0. This library provides 19 custom matchers adapted to the new way of matchers constructing. It allows you to compare DOM Objects relations and states.
jasmine-dom-custom-matchers
for?expect(actual).toBeHTMLElement(name)
[see below]expect(actual).toBeHTMLText(content)
[see below]expect(actual).toBeDocumentNode()
[see below]expect(actual).toContainHTMLElement(descendant)
[see below]expect(actual).toContainText(content)
[see below]expect(actual).toBeChildOf(parent)
[see below]expect(actual).toBeNthChild(index)
[see below]expect(actual).toBeParentOf(child)
[see below]expect(actual).toHaveSameParent(node)
[see below]expect(actual).toHaveChildren(numOfChildren)
[see below]expect(actual).toBeNextSiblingOf(expected)
[see below]expect(actual).toBePreviousSiblingOf(expected)
[see below]expect(actual).toBeEmpty()
[see below]expect(actual).toHaveAnyAttribute()
[see below]expect(actual).toHaveAttribute(name,value)
[see below]expect(actual).toHaveClass(class)
[see below]expect(actual).toHaveComputedStyle(prop,value)
[see below]expect(actual).toHaveComputedColor(prop,value)
[see below]expect(actual).toHaveEvent(event)
[see below]Examine the Samples described below to find out how you can use DOM custom matchers.
Chrome | Firefox | IE | Edge | Safari | Opera | iOS Safari | Opera Mini |
---|---|---|---|---|---|---|---|
4+ | 2+ | 9-11 | 12+ | 3.1+ | 9+ | 3.2+ | all |
expect(actual).toBeHTMLElement(name)
actual
is [HTML Element] Object.name
parameter is optionalname
parameter if passed, must be of type [String]name
parameter if passed, the matcher checks if actual
is a [HTML Element] Object of expected tag name name
name
parameter if passed but not of type [String], is ignored as if it was not passed (matcher checks if actual
is [HTML Element] Object regardless its tag name)actual
is not the [HTML Element] Objectactual
is [HTML Element] Object but of not expected tag name name
(if passed)actual
is [HTML Element] Objectactual
is [HTML Element] Object of expected name
(if passed)actual
[HTML Element] Object is appended to the DOM or notexpect(actual).toBeHTMLText(content)
actual
is [HTML Text] Object.content
parameter is optionalcontent
parameter if passed, must be of type [String] or [RegExp]content
is of type [String] the matcher checks the equality of the actual
text content and expected content
content
is of type [RegExp] the matcher use String.prototype.match() to check if the actual
text content matches the expected content
regular expressioncontent
parameter if passed but not of type [String] or [RegExp], is ignored as if it was not passed (matcher checks if actual
is [HTML Text] Object regardless its content)actual
is not the [HTML Text] Objectactual
is [HTML Text] Object but does not match expected content
(if passed)actual
is [HTML Text] Objectactual
is [HTML Text] Object and matches expected content
(if passed)actual
[HTML Text] Object is appended to the DOM or notexpect(actual).toBeDocumentNode()
actual
is a [HTML Element] Object or [HTML Text] Object appended into DOM Treeactual
is not [HTML Element] Object or [HTML Text] Object or if it is not appended into DOM Treeactual
is [HTML Element] Object or [HTML Text] Object appended into DOM Treeexpect(actual).toContainHTMLElement(descendant)
actual
HTML Element contains expected descendant
actual
and descendant
must be [HTML Element] Objectactual
or descendant
is not the [HTML Element] Objectactual
does not contain descendant
actual
and descendant
is the same objectdescendant
is a child node of actual
descendant
is a farther descendant of actual
actual
[HTML Element] Object and its expected descendant are appended to the DOM or notexpect(actual).toContainText(content)
actual
[HTML Element] Object and all its descendants contain or match expected textual content
content
must be of type [String] or [RegEx]actual
contains multiple of [HTML Text] descendants, it is normalized (empty [HTML Text] nodes and multi spaces are removed from the text) before being compared with expected content
textactual
is not [HTML Element] Object or if content
is not of type [String] or [RegEx]actual
does not contain or match the text or regular expression passed in content
actual
contains or matches the text or regular expression passed in content
actual
[HTML Element] Object is appended to the DOM or notto check whether the [HTML Text] Object equals text content, use
toBeHTMLText(content)
with expected textcontent
expect(actual).toBeChildOf(parent)
actual
[HTML Element] Object or [HTML Text] Object is a children of parent
[HTML Element] Objectactual
is not [HTML Element] Object or [HTML Text] Objectparent
is not [HTML Element] Objectactual
is not a direct child node of parent
actual
and parent
is the same objectactual
is the direct child node of parent
actual
and parent
are appended to the DOM or notexpect(actual).toBeNthChild(index)
actual
[HTML Element] Object has expected index
in the collection of child nodes of actual
's parent [HTML Element] Objectindex
must be of type [Number] equal or greater than 0
or of the [String] value: last
expect(actual).toBeNthChild(0)
the matcher checks if actual
is the first child node of its parentexpect(actual).toBeNthChild(1)
the matcher checks if actual
is the second child node of its parentexpect(actual).toBeNthChild('last')
the matcher checks if actual
is the last child node of its parentactual
is not [HTML Element] Objectindex
is not of type [Number] greater than 0 or if is not of 'last'
valueactual
is not at expected index
inside its [HTML Element] parentactual
has not got [HTML Element] parentactual
is at expected index
inside its [HTML Element] parentactual
and its [HTML Element] parent are appended to the DOM or notexpect(actual).toBeParentOf(child)
actual
[HTML Element] Object is a parent of child
[HTML Element] Object or [HTML Text] Objectactual
is not [HTML Element] Objectchild
is not [HTML Element] Object or [HTML Text] Objectactual
is not a direct parent node of child
actual
and child
is the same objectactual
is the direct parent node of child
actual
and child
are appended to the DOM or notexpect(actual).toHaveSameParent(node)
actual
and node
are the children of the same [HTML Element] Objectactual
and node
must be of type [HTML Element] or [HTML Text]actual
or node
is not [HTML Element] or [HTML Text] Objectactual
and node
are not the children of the same [HTML Element] Objectactual
and node
are the children of the same [HTML Element] Objectactual
and node
are appended to the DOM or notexpect(actual).toHaveChildren(numOfChildren,operator)
actual
[HTML Element] Object contains any [HTML Element] child nodesnumOfChildren
is optional, if passed must be of type [Number] equal or greater than 0
numOfChildren
, if passed the matcher checks if the number of actual
child nodes equals to expected numOfChildren
numOfChildren
is not of type [Number] or is less than 0
, it is ignored as if it was not passedoperator
is optional, if passed must be the one of following [String] values: or more
, or less
, more than
, less than
expect(actual).toHaveChildren(3)
the matcher checks if actual
has got 3 element nodesexpect(actual).toHaveChildren(3,'or more')
the matcher checks if actual
has got 3 or more than 3 element nodesexpect(actual).toHaveChildren(3,'or less')
the matcher checks if actual
has got 3 or less than 3 element nodesexpect(actual).toHaveChildren(3,'more than')
the matcher checks if actual
has got more than 3 element nodesexpect(actual).toHaveChildren(3,'less than')
the matcher checks if actual
has got less than 3 element nodesoperator
is not the one of indicated four values, it is ignored as if it was not passedactual
is not [HTML Element] Objectactual
does not contain any [HTML Element] child nodes (if numOfChildren
not passed)actual
does not contain expected number of [HTML Element] child nodes (if numOfChildren
|operator
passed)actual
contains at least one [HTML Element] child node (if numOfChildren
not passed)actual
contains expected number of [HTML Element] child nodes (if numOfChildren
|operator
passed)actual
[HTML Element] Object is appended to the DOM or notexpect(actual).toBeNextSiblingOf(expected)
actual
[HTML Element] Object is the next element sibling of expected
[HTML Element] Objectactual
and expected
must be of type [HTML Element]actual
or expected
is not [HTML Element] Objectactual
is not the next element sibling of expected
expected
has not got any next element siblingactual
is the next element sibling of expected
actual
and expected
is appended to the DOM or notexpect(actual).toBePreviousSiblingOf(expected)
actual
[HTML Element] Object is the previous element sibling of expected
[HTML Element] Objectactual
and expected
must be of type [HTML Element]actual
or expected
is not [HTML Element] Objectactual
is not the previous element sibling of expected
expected
has not got any previous element siblingactual
is the previous element sibling of expected
actual
and expected
is appended to the DOM or notexpect(actual).toBeEmpty()
actual
[HTML Element] Object has not got any [HTML Element] or [HTML Text] child nodesactual
is not [HTML Element] Objectactual
contains at least one [HTML Element] Object or [HTML Text] Objectactual
has not got any [HTML Element] or [HTML Text] descendantactual
[HTML Element] Object is appended to the DOM or notthe difference between .toBeEmpty() matcher and .toHaveChildren() matcher is that .toBeEmpty() matcher checks if the actual [HTML Element] Object contains both [HTML Element] and [HTML Text] Objects when .toHaveChildren() matcher checks if the actual [HTML Element] Object contains only [HTML Element] Objects.
expect(actual).toHaveAnyAttribute()
actual
[HTML Element] Object has got any attribute definedactual
is not [HTML Element] Objectactual
is has not got any attribute definedactual
is has got at least one attribute definedexpect(actual).toHaveAttribute(name,value)
actual
[HTML Element] Object has expected attribute name
of expected value
name
must be of type [String]value
parameter is optional, if not passed, matcher checks if actual
has expected attribute name
regardless its valuevalue
parameter if passed, must be of type [String] or of type [RegExp]value
is not of type [String] or of type [RegExp], it is ignored as if it was not passed (matcher checks if actual
has expected attribute name
regardless its value)value
is of type [String] the matcher checks the equality of attribute's value and expected value
value
is of type [RegExp] the matcher use String.prototype.match()
to check if the attribute's value matches the expected regular expression value
actual
is not [HTML Element] Object or if name
is not of type [String]actual
does not have expected attribute name
(if value
not passed)actual
does not have expected attribute name
of expected value
(if value
passed)actual
has expected attribute name
(if value
not passed)actual
has expected attribute name
of expected value value
(if value
passed)actual
is appended to the DOM or notwith appropriate /regular expression/ passed as
value
parameter it is possible to check whether class attribute contains expected class, but it is easier to achieve with .toHaveClass() custom matcher
expect(actual).toHaveClass(class)
actual
[HTML Element] Object has got class attribute with expected value class
from among the list of classesclass
must be of type [String]actual
is not [HTML Element] Object or if class
is not of type [String]actual
has not got expected class
setactual
has got expected class
setactual
is appended to the DOM or notto check whether [HTML Element] Object has got a class attribute defined regardless its values, use
.toHaveAttribute('class')
matcher
expect(actual).toHaveComputedStyle(prop,value)
actual
[HTML Element] Object's computed prop
style is of expected value
actual
must be appended into the DOM tree, so that the [CSSStyleDeclaration] Object could be returnedprop
must be of type [String] (both camelCase and hyphen-case are accepted)value
must be of type [String] or [RegExp]value
is of type [String] the matcher checks the equality of the computed style's value and expected value
value
is of type [RegExp] the matcher use String.prototype.match()
to check if the computed style's value matches the expected value
regular expressionactual
is not [HTML Element] Object or prop
is not of type [String] or value
is not of type [String] or [RegExp]prop
propertyactual
has got the computed prop
style of the different value than expected value
actual
has got the computed prop
style of the same value as expected [String] value
or if computed prop
style matches expected [RegExp] value
in order to deal with the differences between browsers of returning computed style values, use regular expression
.toHaveComputedStyle('propertyName',/(ms-value|moz-value|webkit-value)/)
expect(actual).toHaveComputedColor(prop,value)
actual
[HTML Element] Object's computed prop
style is of expected value
toHaveComputedStyle()
and toHaveComputedColor()
is that toHaveComputedColor()
is convenient to compare each CSS *-color
property, which demand or return color value (background-color
, border-bottom-color
, color
, box-shadow
, text-shadow
, outline-color
, etc.)value
in the format of your choice (#HEX
RGB()
or HSL()
), regardless which format the browser return as computedactual
must be appended into the DOM tree, so that the [CSSStyleDeclaration] Object could be returnedprop
must be of type [String] (both camelCase and hyphen-case are accepted)value
must be of type [String] (in order to use [RegExp] value, use matcher toHaveComputedStyle('colorProp',/regEx/)
)actual
is not [HTML Element] Object or prop
is not of type [String] or value
is not of type [String]prop
propertyactual
computed prop
style does not match expected value
coloractual
computed prop
style matches expected value
colorIf the browser return
rgb(255, 255, 0) 2px 2px 2px
as computed 'box-shadow' style, the expectedvalue
rgb(255, 255, 0)
,rgba(255, 255, 0, 1)
,#ff0
,#FFFF00
,hsl(60, 100%, 50%)
andhsla(60, 100%, 50%, 1)
will return truthy result.If the browser return
rgba(255, 255, 0, .4)
as computed 'color' style, the expectedvalue
rgba(255, 255, 0, .4)
andhsla(60, 100%, 50%, .4)
will return truthy result.If the browser return
rgba(255, 255, 0, .4)
as computed 'color' style, the expectedvalue
rgb(255, 255, 0)
,#ff0
,#FFFF00
andhsl(60, 100%, 50%)
will return faulty result because the alpha parameter does not match.Because of the differences between browsers, the
alpha
parameter ofhsla()
andrgba()
formats is rounded to two digits after decimal point. The same result will be aimed withrgba(100, 100, 100, 0.23)
,rgba(100, 100, 100, 0.230445)
,rgba(100, 100, 100, 0.2349999999)
expect(actual).toHaveEvent(event)
actual
[HTML Element] Object has got expected event
attachedaddEventListener()
method
actual.onclick = fireClick
this event will be detectedactual.addEventListener('click',fireClick)
this event will not be detectedevent
must be of type [String] and must indicate expected event name, eg. click
, mouseover
, focuson
, resize
(both click
and prefixed onclick
syntax accepted)actual
is not [HTML Element] Object or event
is not of type [String]event
is not recognized event nameactual
has not got expected event
attachedactual
has got expected event
attached by the addEventListener()
methodactual
has got expected event
attachedactual
is appended to the DOM or notEach matcher demands accurate type of parameter value. The matcher check the
actual
andexpected
parameters' types before implementing the comparison and return false when value type is incorrect regardless the comparison result.Compared [HTML Element] and [HTML Text] Objects do not have to be appended to the DOM tree in order to use DOM custom matcher. The comparison can be implemented for dynamically created elements in
beforeEach()
,beforeAll()
orit()
scope. Exception is.toBeDocumentNode()
matcher which check ifactual
Object is appended to the DOM and.toHaveComputedStyle()
.toHaveComputedColor()
matchers which require the [HTML Element] Object to be appended to the DOM in order to return the expected computed styleIn order to check whether two HTML Objects are the same objects use the native matcher
expect(objectA).toBe(objectB)
In order to check whether two HTML Objects are equal objects use the native matcher
expect(objectA).toEqual(objectB)
npm install jasmine-dom-custom-matchers --save-dev
var matchers = require('jasmine-dom-custom-matchers'); //get the module
describe("The new DIV element", function() {
beforeAll(function() {
jasmine.addMatchers(matchers); //set custom matchers for jasmine
this.newDiv = document.createElement('DIV');
});
it("should be empty.", function() {
expect(this.newDiv).toBeEmpty(); //do the magic with new DOM matchers
});
}
You can use
karma-html
module to test your.html
files in thekarma
browser runner [git] [npm]
Use karma-jasmine-dom
package [link] that adapts the jasmine-dom-custom-matchers
package for karma
.
dom-matchers.js
in html file<head>
<link rel="shortcut icon" type="image/png" href="https://github.com/devrafalko/jasmine-dom-custom-matchers/blob/master/jasmine/lib/jasmine-core/jasmine_favicon.png">
<link rel="stylesheet" type="text/css" href="https://github.com/devrafalko/jasmine-dom-custom-matchers/blob/master/jasmine/lib/jasmine-core/jasmine.css">
<script type="text/javascript" src="https://github.com/devrafalko/jasmine-dom-custom-matchers/raw/master/jasmine/lib/jasmine-core/jasmine.js"></script>
<script type="text/javascript" src="https://github.com/devrafalko/jasmine-dom-custom-matchers/raw/master/jasmine/lib/jasmine-core/jasmine-html.js"></script>
<script type="text/javascript" src="https://github.com/devrafalko/jasmine-dom-custom-matchers/raw/master/jasmine/lib/jasmine-core/boot.js"></script>
<script type="text/javascript" src="https://github.com/devrafalko/jasmine-dom-custom-matchers/raw/master/dom-matchers.js"></script>
</head>
Any outer libraries needed. It is a fully JavaScript library.
jasmine.addMatchers
in your tests filesdescribe("The new DIV element", function() {
beforeAll(function() {
//DOMCustomMatchers is the global window object got from dom-matchers.js
jasmine.addMatchers(DOMCustomMatchers);
this.newDiv = document.createElement('DIV');
});
it("should be empty.", function() {
expect(this.newDiv).toBeEmpty(); //do the magic with new DOM matchers
});
}
karma-html
to test your .html
files in the karma
browser runner [git] [npm]karma-jasmine-dom
package to use jasmine-dom-custom-matchers
with karma [npm]jasmine
custom matchers docs [link]jasmine
installation [link]Released under the MIT license.
Copyright (c) 2017 Paweł Rafałko dev.rafalko@gmail.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.