Data-tree-snapshot NPM

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
                        "
            `)
})