Helper library for unexpected plugins that perform assertions on XML like structures
npm install unexpected-htmllike
!tattoo
(Image from http://www.idyllramblings.com/2010/03/the-geekiest-tattoos-you-ever-did-see.html)
Beautifully painted magicpen generation and output of diffs and inspections for HTML-like structures.
IMPORTANT: This is not a plugin for unexpected. This is a helper library for
plugins for unexpected, that perform assertions and/or inspections on HTML-like structures, such as the DOM,
React Elements (including JSX), and React shallow renderer.
This project is now used for production tests in a number of projects. If you find something that doesn't diff properly,
please report it in the github issues: https://github.com/bruderstein/unexpected-htmllike/issues
inspect, diff and contains methods are provided, allowing diffing of any HTML/XML like structure, including wrapper detection.
e.g.
Assuming a "actual" representation of the following
``xml`
Some text
If the expected is
`xml`
Some text
This (optionally) matches. This also works even if the content inside the wrapper doesn't match exactly. If that is the case,
the wrapping element is output greyed out, with the changes highlighted (use in the options).
You can also diff wrappers, and they will be highlighted as wrappers that should be removed (use diffWrappers: true, the default, in the options).
The items that "count" towards a match can be controlled with options.
Create an instance of UnexpectedHtmlLike, passing an adapter as the only parameter.
Use unexpected-htmllike-reactrendered-adapter for
DOM rendered React components, and unexpected-htmllike-jsx-adapter
for JSX (ReactElement) adapter - useful for shallow rendering and asserting on JSX structures.
`js
expect.addAssertion('
const adapter = new ReactElementAdapter();
const jsxHtmlLike = new UnexpectedHtmlLike(adapter);
const diffResult = jsxHtmlLike.diff(adapter, subject, expected, expect, options);
return jsxHtmlLike.withResult(diffResult, result => {
if (result.weight !== 0) {
return expect.fail({
diff: function (output, diff, inspect) {
return {
diff: jsxHtmlLike.render(result, output, diff, inspect)
};
}
});
}
});
});
`
If you want to use one of the exising adapters, you can skip this section - this is only if you want to implement your own adapter.
You need to create an object, with the following methods:
, getName would return input.getChildren(element)
Returns either an array of elements (or content). The elements should be either further elements that the methods of this object can call,
or native content. For instance, , would return [ 'the content' ]. If the element has no children, an empty array
should be returned.getAttributes(element)
Returns an object with each attribute as a key/value pair. Note that when outputting, outputs string attributes in double quotes,
and other content types in curly braces ({ }). This matches the React/JSX style of attribute definition. If you want to force quoted attributes (such
as XML or HTML output), simply ensure the attribute values are strings.classAttributeName (since 0.4.0)
Property that holds the string name of the class attribute. This normally class, but could be className in the case
of ReactElement (i.e. JSX) When diffing, if the classAttributeName is the same for both actual and expected adapters,
then the classes can be optionally diffed using class semantics.API
constructor (adapter)
Pass the adapter object (ie. an object with
getName, getAttributes, and getChildren methods)
e.g.`js
var JsxAdapter = require('unexpected-htmllike-jsx-adapter');
var UnexpectedHtmlLike = require('unexpected-htmllike');var jsxDiff = new UnexpectedHtmlLike(new JsxAdapter());
`inspect(actual, depth, output, inspect)
Returns a formatted output of the element () using magicpen
Parameters are the same as for the unexpected inspect methoddiff(expectedAdapter, actual, expected, expect, options)
Diffs actual against expected, returning either a promise or the diff result. Note that a second adapter
is passed for the expected, such that it is possible to diff two otherwise incompatible representations. If you want
to diff the same type as the "actual" (e.g. comparing JSX with JSX), simply pass the same adapter as the expectedAdapter.options can be null, or an object with the following flags (all are optional, and all boolean flags default to true).
$3
When true (the default), if a child element is missing in the actual, this is counted as a mismatch, and highlighted in the output$3
When true (the default), if a child element appears in the actual, but not in the expected, this is counted as a mismatch,
and highlighted in the output.$3
When true (the default), if an attribute appears in the expected, but not in the actual, this is counted as a mismatch, and
is highlighted in the output.$3
When true (the default), if an attribute appears in the actual, but not in the expected, this is counted as a mismatch, and
is highlighted in the output. It is anticipated that most usages will set this to false, to allow for a 'to satisfy' style
of assertion, but the default is true to ensure that the default is always an exact match.$3
When true (the default), if an element is found in the actual to be wrapping what is expected, it is highlighted as a wrapper
that should be removed. When false, if the content does not match exactly (ie. diff returns a weight of non-zero - see return value),
then the wrapper is outputted in grey (the prismPunctuation style), and is always separated onto a separate line.$3
When true (the deafult), the class (or className, depending on the adapter) attribute will be diffed as all other
string attributes - i.e. a single space difference will be considered different. When false, then HTML class semantics
are used, such that order is irrelevant, multiple spaces are ignored, and the following two flags can be used to ignore
either missing or extra classes.
Note that the class attribute for the actual and expected adapters must be the same in order to use these flags.
This means that they will not have any effect if comparing (for example) the DOM (using class attribute) with React
JSX (using className attribute). This may change in a future release.$3
When true, and diffExactClasses is false, then any extra classes in the actual are treated as a diff. When false, extra
classes are ignored. This is the most likely flag to be false when diffing, as it is likely you wish to ignore extra classes
on the actual over what was expected.
e.g. actual:
expected:
This will match when is false, as the class special is ignored. When true, these two items would
not be treated as being the same. Note that the order is irrelevant.
Note that the class attribute for the actual and expected adapters must be the same in order to use these flags.
This means that they will not have any effect if comparing (for example) the DOM (using class attribute) with React
JSX (using className attribute). This may change in a future release.$3
When true (the default), and diffExactClasses is false, then any missing classes in the actual are treated as a diff.
When false, missing classes from the actual (based on the expected classes) are ignored.
Note that the class attribute for the actual and expected adapters must be the same in order to use these flags.
This means that they will not have any effect if comparing (for example) the DOM (using class attribute) with React
JSX (using className attribute). This may change in a future release.$3
This allows finding an actual child identified by an attribute on the expected. For instance, when
findTargetAttrib is set to 'eventTarget', and presented with the following "actual" value (in some XML/HTML representation with an appropriate adapter)`xml
foo
bar
baz
`The expected value is then (expressed in JSX syntax, the value of the attribute must be
):`xml
`In this case, (assuming
is false in the options) the resulting diff will contain a target property, which is the element from the actual value (in whatever form that object takes).
When set, the result of the diff contains a
target property, which is the matching "actual" element that matched the "expected" element with the given attribute as true.It is anticipated to use this to identify a child component on which to trigger an event, or a child component to identify.
e.g. (using unexpected-react as an example)
`js
// With eventTarget set as findTargetAttrib
expect(todoList, 'with event click', 'on',
'to contain', Completed! );
// With set as findTargetAttrib
expect(todoList, 'queried for',
'to have rendered', Label of item 2);
* For
, the target is a direct property of the result.
* For contains(), the target is under the bestMatch property. i.e.
`js
var containsResult = htmlLikeInstance.contains(adapter, actual, expected, expect, options);if (containsResult.found) {
const foundTarget = containsResult.bestMatch.target;
// ...
}
`
$3
This must be an object that represents the different weights for the various differences that can occur.
The weights that can be provided, and the defaults are shown here
js
{
NATIVE_NONNATIVE_MISMATCH: 15,
NAME_MISMATCH: 10,
ATTRIBUTE_MISMATCH: 1,
ATTRIBUTE_MISSING: 1,
ATTRIBUTE_EXTRA: 1,
STRING_CONTENT_MISMATCH: 3,
CONTENT_TYPE_MISMATCH: 1,
CHILD_MISSING: 2,
CHILD_INSERTED: 2,
WRAPPER_REMOVED: 3,
ALL_CHILDREN_MISSING: 8
};
`The weights are used to detect wrapper elements by identifying that when the wrapping element is removed,
the weight of the diff is less than the diff when it remains there.
This can be easily demonstrated:
xml
here is some text
`If we diff against the following
xml
here is some different text
`
This (without wrapper detection), would result in the following points being found:
* should be a div (NAME_MISMATCH == 10)
* id="different-content" attribute missing (ATTRIBUTE_MISSING == 1)
* className="wrapper-example" extra attribute (ATTRIBUTE_EXTRA == 1)
* here is some text should be the simple content text here is some text (NATIVE_NONNATIVE_MISMATCH == 15)
... which is a total weight of 10 + 1 + 1 + 15 = 27Removing the wrapper, results in
*
id="content" should be id="different-content" (ATTRIBUTE_MISSMATCH == 1)
* here is some text should be here is some different text (STRING_CONTENT_MISMATCH == 3)
... which is a total weight of 1 + 3 = 4If
diffWrappers == true, then WRAPPER_REMOVED (== 3) is added to this.$3
diff may return a promise, which resolves with an object with the following 2 properties, or it may return the object directly.
Check for the existence of then, if it exists, treat it as a promise.The returned object, or the resolved value contains the following properties:
*
weight - the resulting weight from the diff. If this is 0, the actual and expected match according to the options provided.
* diff - the internal diff representation. Pass to the render() method to actually render the output.Note that the promise is always resolved (unless of a bug or a real issue in a assertion), whether a difference is recorded or not.**
To check that the
actual and expected are equivalent (given the options provided), check that the weight is zero.contains (expectedAdapter, actual, expected, expect, options)
Checks if the
expected is contained somewhere within the actual. The arguments are the same as the diff function,
including the options for flags and weights (options can also be null, to accept the defaults). See the description of diff
for information on the parameters.$3
returns either a promise that resolves to an object, or the object directly, with the following properties
* found - (boolean) - true if a match was found
* bestMatch - (object) - if found is false, bestMatch contains the best located match, and is the same result as the diff function.
That is to say that bestMatch has the following properties:
* weight - (number) the weight of the diff - larger numbers indicate a bigger difference (see the description of diff above)
* diff - the internal diff representation that you can pass to render() to output the actual output
* bestMatchItem - this is the element in whatever form the actual value takes that matched the best. This could be useful to identify the actual
node that matched the best, and is provided only for convenience.Note that the promise is always resolved (unless of a bug or a real issue in a assertion), whether the content is
found or not.withResult(value, callback)
Neatly handle the difference between a promise and a value return value.
e.g.
`js
var diffResult = htmlLike.diff(expectedAdapter, actual, expected, expect, {});
htmlLike.withResult(diffResult, function (result) { // Here
result is the actual result, whether or not the return value of the diff
// function was a promise
htmlLike.render(result, output, diff, inspect);
});
render(diffResult, output, diff, inspect)
Outputs the given internal diff structure to the given output magicpen instance.
and inspect should be the functions passed in to the diff function, but in most cases can
be the expect.diff and expect.inspect variants (keep in mind this won't always work, and is not recommended)$3
For convenience, it returns the
output parameter. Contributing
Absolutely! Do it! Raise a pull request, an issue, make a comment. If you do make an addition or change, please make sure there are
tests to go with the changes. Each module has a
.spec.js file to go with it. Tests for diff usually have a direct test, and an integration
level test in HtmlLike.spec.js, that tests that the correct output is given when the output of diff is passed to the painter. painter.js is
responsible for outputting the diff or element description to a magicpen instance. This separates the diffing and output generation, which is helpful
for wrapper detection, as some elements may need to be diffed several times to check for wrappers. Leaving the output generation to the end means this
process is a little more efficient.Roadmap / Future plans
We may need to extend the interface of the adapters to allow for "special" elements (such as