data-tree-snapshot
v2.0.0
Published
Snapshot test the compacted tree structure of tagged parts of the DOM
Downloads
208
Maintainers
Readme
Data Tree Snapshot 🌳🤳
Intro
Create the smallest possible representation of the tree structure of the values of any attribute or property contained in a DOM element. data-tree-snapshot
only preserves ancestor/descendant relationships because it is used to assert that a given element contains a certain structure. This compacted tree structure is created recursively for the entire DOM tree within the given DOM element.
Installation
npm install data-tree-snapshot -D
API
getTextTree
(Text Snapshotting, named export)
import React from 'react'
import { render } from '@testing-library/react'
import { getTextTree } from 'data-tree-snapshot'
test('has correct textContent', () => {
// This is just an example. Normally, the JSX output would be a result of rendering
// your app or a subset of your app and taking actions to get it into a given state
const { container } = render(
<div>
Heading
<div>
Subheading
<div>Paragraph 1</div>
<div>Paragraph 2</div>
<div>Paragraph 3</div>
</div>
</div>,
)
const tree = getTextTree(container)
expect(tree).toMatchInlineSnapshot(`
"
Heading
Subheading
Paragraph 1
Paragraph 2
Paragraph 3
"
`)
})
Implementation
import makeGetDataTree from '../make-get-data-tree'
// 👆The default export of data-tree-snapshot, used to create data tree getters
export default makeGetDataTree({
propertyName: 'textContent',
filter: t => typeof t === 'string' && t.length > 0,
})
getTestIdTree
(Test Id Tree Snapshotting, named export)
import React from 'react'
import { render } from '@testing-library/react'
import { getTestIdTree } from 'data-tree-snapshot'
test('shows correct components for scenario', () => {
render(
// This is just an example. Normally, the JSX output would be a result of rendering
// your app or a subset of your app and taking actions to get it into a given state
<div data-testid="root">
<div>
<div data-testid="parent">
<div data-testid="child">
<div>
<div>
<span data-testid="deeply-nested-child">some stuff</span>
</div>
</div>
</div>
<br data-testid="another-child" />
<div>
<br data-testid="yet-another-child" />
</div>
</div>
</div>
</div>,
)
// 👇 You can pass either a data-testid string or an element itself
expect(getTestIdTree('root')).toMatchInlineSnapshot(`
"
parent
child
deeply-nested-child
another-child
yet-another-child
"
`)
})
Note: You can change the test id attribute that is used by default by using configure
(see below)
(Lots more good info about this helper on the wiki page!)
Implementation
import makeGetDataTree from '../make-get-data-tree'
// 👆The default export of data-tree-snapshot, used to create data tree geters
// If you use an attribute, the default string selector will be for that attribute
// e.g. document.querySelector('[data-testid="your-test-id-name"]') will be used for getTestIdTree
export default makeGetDataTree({
attributeName: 'data-testid',
filter: t => typeof t === 'string' && t.length > 0,
})
makeGetDataTree
This is a function that creates a custom getDataTree function based on the following options object, represented here as a TypeScript interface:
interface options {
// formats the value
// value is the attribute or property we've gotten from the element
// based on attributeName or propertyName
format?: (value) => boolean
// Only values / elements for which this returns true will be included
filter?: (value, element) => boolean
attributeName?: string
propertyName?: string
}
The only requirement is that either attributeName
or propertyName
are passed (but not both).
The type of the returned get function is as follows elementOrString => string
, where elementOrString
is either an HTML element or a string value to be used as a selector for the given attributeName
(passing a string selector for property tree geters is currently unsupported).
For example, when calling getTestIdTree('root')
, document.querySelector('[data-testid="root"]')
will be called to get the root element for which to get the test id tree.
Full example:
const getLabelTree = makeGetDataTree({
attributeName: 'label',
filter: l => typeof l === 'string' && l.length > 0,
})
getLabelTree('some-label-value') // document.querySelector(`[label="some-label-value"]`) will be called to get the root element
configure
Configure a custom test id attribute to be used by getTestIdTree
instead of data-testid
.
import React from 'react'
import { cleanup, render } from '@testing-library/react'
import getTestIdTree from '.'
import configure from '../configure'
test('Can use a custom data-testid attribute', () => {
const TestComponent = () => {
return (
<div data-qa="root">
<br data-qa="first-child" />
<br data-qa="second-child" />
<br data-qa="third-child" />
</div>
)
}
// This could live in your jest setup if you want it to apply to all tests
configure({ testIdAttribute: 'data-qa' })
render(<TestComponent />)
const tree = getTestIdTree('root')
expect(tree).toMatchInlineSnapshot(`
"
first-child
second-child
third-child
"
`)
})
Upcoming Features
- Include multiple pieces of data per element
- Configure selectors for property getters