# Testing
The goal of the test API is to enable developers to write robust tests that rarely need to be updated when the library is upgraded. When changes are required, they will be well documented in the Change Log in the same way all other API changes are documented.

The test API can be used with any test framework.

## Test Hooks
Test hooks are `data` attributes rendered by every component that facilitate interactions with the component. There are two types of test hooks:

* Element Selectors - Uniquely identify interactive elements within each component. These elements are often clicked on or have text that is entered into them. An example element selector is the toggle that opens and closes a `Select`'s popover menu.

* State Attributes - Provide current state information. These `data` attributes are rendered in the root of the component. An example state attribute is the current value of a `Select` component.

## Writing Robust Tests

* DO add a `data-test` attribute to the root of interactive components to uniquely identify them on the page. For example, if you have a page with multiple `Select` components, give each one a `data-test` attribute that is scoped to the project it is used in and describes what it does. For example, `data-test="user-preferences:select-default-color"`.

* Do scope selectors. If you need an element within a component, scope your selector within that component. This prevents future conflicts when other components are added later.

* NEVER use raw DOM elements in selectors. The rendered DOM of components changes frequently, even in patch versions. Tests that rely on a particular DOM structure frequently fail when the library is upgraded. Only use the hooks provided by the test API. If you find a hook missing or broken, please file a bug.

* NEVER rely on the order of components or elements. Instead, add a `data-test` attribute to uniquely identify the component. For example, if you have a `Modal` with two buttons, cancel and submit, in the footer, add `data-test="cancel"` and `data-test="submit"` to those buttons rather than relying on the submit button coming after the cancel button.

## Animation
It's often useful to be able to turn off animation when running tests so that they run faster. The [AnimationToggle](AnimationToggle) component can be used to control your own animation and the animation in `@splunk/react-ui` through a `Provider`.