docs: update the documentation of the tests

Author: git-nandor

docs/testing/converting-old-tests.md

@@ -1,10 +1,10 @@
 ---
-title: Real-world component testing
+title: Cypress component testing
 category: Testing
-order: 5
+order: 3
 ---
 
-# Real-world component testing
+# Cypress component testing
 
 Sometimes unit test behaviour doesn't match how our components work in the browser (e.g. no ResizeObserver)
 InstUI uses [Cypress Component Testing](https://docs.cypress.io/guides/component-testing/overview) for these cases. These are located at `instructure-ui/cypress/component/`.
@@ -28,7 +28,7 @@ Cypress tests usually have a structure like this:
 type: code
 ---
 import React from 'react'
-import { ComponentToTest } from '../../packages/ui'
+import { ComponentToTest } from '@instructure/ui'
 import '../support/component'
 
 describe('<ComponentToTest/>', () => {

docs/testing/integration-testing.md docs/testing/cypress-component-testing.mddocs/testing/integration-testing.md renamed to docs/testing/cypress-component-testing.md

@@ -0,0 +1,27 @@
+---
+title: Testing
+category: Testing
+order: 1
+---
+
+## Testing
+
+This page provides an overview of the testing strategies we use to ensure the quality and stability of our components. We use a combination of modern tools to support our testing needs. Each tool serves a different purpose in our testing pyramid, from unit-level validations to full-blown visual and behavioral regression tests.
+
+### Technologies Used:
+
+#### Vitest + React Testing Library:
+
+These tools are our primary stack for writing component-level unit tests. They are lightweight and fast. [Vitest](https://vitest.dev/guide/) is one of the fastest modern testing framework. It offers a Jest-like API and runs in a Node.js environment, making it ideal for testing individual components and functions in isolation. Paired with [React Testing Library](https://testing-library.com/docs/react-testing-library/intro), Vitest encourages accessible and maintainable test practices by querying elements the way users interact with them. It's best suited for testing component logic, rendering conditions, and props/state changes without needing a full browser environment.
+
+#### Cypress Component Testing:
+
+[Cypress Component Testing](https://docs.cypress.io/app/component-testing/get-started) allows you to mount individual components in a real browser environment for precise interaction testing. Unlike traditional unit tests, it renders with full CSS and browser APIs, offering more realistic behavior. This makes it ideal for testing user interactions like clicks, keyboard navigation, focus traps, and animations. While a bit heavier than Vitest, it provides greate visibility and debugging capabilities for complex UI logic.
+
+#### Chromatic Visual Regression Testing with Cypress:
+
+We use [Cypress](https://docs.cypress.io/app/tooling/visual-testing) end-to-end tests to generate structured layouts and capture screenshots of components. [Chromatic](https://www.chromatic.com/docs/diff-inspector/) handles the visual diffing and review process. It's especially effective for catching layout shifts, styling regressions, or broken UI elements that don’t trigger functional test failures. Tests are run after changes are pushed, comparing the new screenshots to a baseline stored from a previously verified state. When differences are detected, the test fails and provides side-by-side diffs for easy review. This type of testing is particularly valuable for pixel-perfect components, design systems, or any feature with strict visual requirements.
+
+#### Cypress Behavioral Regression Testing:
+
+[Cypress Behavioral Regression Testing](https://docs.cypress.io/app/end-to-end-testing/writing-your-first-end-to-end-test) focuses on simulating realistic user flows across complex components or pages to ensure key behaviors remain stable. These tests often replicate critical workflows like navigation, and keyboard interactions. They are useful after feature changes or refactors, as they verify that the components still behaves correctly from the user’s perspective. Since the tests run in a real browser, they provide visibility into full-stack behavior, including browser APIs. These more complex end-to-end style tests are helps catch integration issues or regressions that unit and visual tests may overlook.

docs/testing/testing-components.md

@@ -0,0 +1,91 @@
+---
+title: Vitest component testing
+category: Testing
+order: 2
+---
+
+## Vitest component testing
+
+[Vitest](https://vitest.dev/guide/) is our fastest tool for in-memory testing of components and logic in a Node.js environment. We pair it with [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) to validate behavior, rendering, and edge cases—all without requiring a real browser.
+
+### Running Vitest
+
+Vitest can be run from the project root with the following command. It's configured in our CI pipeline so pushing a branch to remote runs these tests automatically.
+
+```
+npm run test:vitest
+```
+
+### Creating new tests
+
+Current tests can be found next to the component source code in the `__tests__` subfolder. New tests should be added there.
+
+Vitest tests usually have a structure like this:
+
+```js
+---
+type: code
+---
+import { render, screen } from '@testing-library/react'
+import { vi } from 'vitest'
+
+import '@testing-library/jest-dom'
+import ComponentToTest from '../index'
+
+describe('<ComponentToTest/>', () => {
+  it('works as intended...', () => {
+    const onClickMock = vi.fn()
+    render(<ComponentToTest onClick={onClickMock}/>)
+    // rest of the test comes here
+  })
+})
+```
+
+### Example
+
+The `ui-avatar` tests can be found [here](https://github.com/instructure/instructure-ui/tree/master/packages/ui-avatar/src/Avatar/__tests__).
+
+### Debugging tests
+
+If you need to debug a test in your IDE or print extra info, you can use:
+
+```
+console.log('Debug info')
+```
+
+To inspect the rendered DOM and current test state, you can also use:
+
+```
+screen.debug()
+```
+
+### Simulating Real User Interactions
+
+While fireEvent from React Testing Library works for basic interaction simulation, we use @testing-library/user-event for more realistic and accessible user interaction testing.
+[userEvent](https://testing-library.com/docs/user-event/intro/) is a companion library for Testing Library that provides more advanced simulation of browser interactions than the built-in fireEvent method.
+While fireEvent dispatches single DOM events, userEvent can fire multiple events and do additional checks along the way, making your tests closer to actual user experience.
+
+Use it in the following way:
+
+```js
+---
+type: code
+---
+import { render, screen } from '@testing-library/react'
+import { vi } from 'vitest'
+
+import '@testing-library/jest-dom'
+import userEvent from '@testing-library/user-event'
+import ComponentToTest from '../index'
+
+describe('<ComponentToTest/>', () => {
+  it('works as intended...', async () => {
+    const onKeyDownMock = vi.fn()
+    render(<ComponentToTest onKeyDown={onKeyDownMock}/>)
+
+    const input = screen.getByTestId('input')
+    await userEvent.type(input, 'foo bar{enter}')
+    // rest of the test comes here
+  })
+})
+```