@codyswann/lisa 2.195.4 → 2.195.6

package/plugins/lisa-expo/.codex-plugin/skills/testing-library/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: testing-library
+description: "Enforces best practices for…"
+---
+
+# Testing Library Best Practices
+
+## Overview
+
+This skill enforces best practices for unit testing in Expo applications using Jest, `@testing-library/react-native`, and `jest-expo`. Tests should be **user-centric**, **accessible**, and **behavior-focused** rather than implementation-focused.
+
+## Core Principles
+
+### 1. Test User Behavior, Not Implementation
+
+Focus on what the component does from a user's perspective, not how it achieves it internally.
+
+```typescript
+// Correct - tests visible behavior
+expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled();
+
+// Incorrect - tests implementation details
+expect(component.state.isSubmitting).toBe(false);
+```
+
+### 2. Use Accessible Queries
+
+Queries should reflect how users and assistive technologies interact with the UI.
+
+```typescript
+// Correct - uses accessible role and name
+screen.getByRole("button", { name: /save changes/i });
+
+// Incorrect - relies on implementation detail
+screen.getByTestId("save-btn");
+```
+
+### 3. One Assertion Per Behavior
+
+Each test should verify one behavior. Multiple assertions are acceptable when verifying different aspects of the same behavior.
+
+```typescript
+// Correct - focused test
+test("displays error message when submission fails", async () => {
+  render(<Form />);
+  await userEvent.press(screen.getByRole("button", { name: "Submit" }));
+  expect(await screen.findByRole("alert")).toHaveTextContent("Failed");
+});
+
+// Incorrect - testing multiple behaviors
+test("form works correctly", async () => {
+  // Tests validation, submission, success, and error handling...
+});
+```
+
+### 4. Prefer userEvent Over fireEvent
+
+`userEvent` simulates realistic user interactions including the full event sequence.
+
+```typescript
+// Correct - realistic interaction
+const user = userEvent.setup();
+await user.press(screen.getByRole("button", { name: "Submit" }));
+
+// Less ideal - simplified event
+fireEvent.press(screen.getByRole("button", { name: "Submit" }));
+```
+
+## Query Priority
+
+Choose queries based on accessibility, following this priority order:
+
+| Priority | Query            | When to Use                             |
+| -------- | ---------------- | --------------------------------------- |
+| 1        | `getByRole`      | Interactive elements, headings, buttons |
+| 2        | `getByLabelText` | Form fields with labels                 |
+| 3        | `getByText`      | Non-interactive content, static text    |
+| 4        | `getByTestId`    | Last resort when semantic queries fail  |
+
+For detailed query patterns, see [references/query-priority.md](references/query-priority.md).
+
+## Async Testing Patterns
+
+### Use findBy for Async Assertions
+
+```typescript
+// Correct - waits for element to appear
+expect(await screen.findByRole("alert")).toBeOnTheScreen();
+
+// Incorrect - may fail if element appears async
+expect(screen.getByRole("alert")).toBeOnTheScreen();
+```
+
+### Use waitFor for Side Effects
+
+```typescript
+// Correct - assertion inside waitFor
+await waitFor(() => {
+  expect(mockCallback).toHaveBeenCalledWith("success");
+});
+
+// Incorrect - side effect inside waitFor
+await waitFor(() => {
+  fireEvent.press(button); // Never do this
+});
+```
+
+For comprehensive async patterns, see [references/async-patterns.md](references/async-patterns.md).
+
+## Mocking Patterns
+
+### Required Global Mocks
+
+These must be configured in `jest/setup-jest.ts`:
+
+```typescript
+// AsyncStorage
+jest.mock("@react-native-async-storage/async-storage", () =>
+  require("@react-native-async-storage/async-storage/jest/async-storage-mock")
+);
+
+// Expo Fonts (to avoid async icon assertions)
+jest.mock("expo-font", () => ({
+  ...jest.requireActual("expo-font"),
+  isLoaded: jest.fn(() => true),
+}));
+```
+
+For complete mocking patterns, see [references/mocking-patterns.md](references/mocking-patterns.md).
+
+## Expo Router Testing
+
+Use `renderRouter` from `expo-router/testing-library` instead of `render` when testing components that use Expo Router.
+
+```typescript
+import { renderRouter, screen } from "expo-router/testing-library";
+
+test("navigates to player detail", async () => {
+  renderRouter({
+    index: () => <PlayerList />,
+    "players/[id]": () => <PlayerDetail />,
+  });
+
+  await userEvent.press(screen.getByRole("button", { name: "View Player" }));
+  expect(screen).toHavePathname("/players/123");
+});
+```
+
+For Expo Router testing details, see [references/expo-router-testing.md](references/expo-router-testing.md).
+
+## Test Structure
+
+### File Organization
+
+- Place test files in `__tests__/` directories, not alongside source files
+- Never place tests inside the `app/` directory (Expo Router constraint)
+- Use `.test.ts` or `.test.tsx` extensions
+
+### AAA Pattern
+
+Structure every test with Arrange-Act-Assert:
+
+```typescript
+test("increments counter when button pressed", async () => {
+  // Arrange
+  const user = userEvent.setup();
+  render(<Counter initialCount={0} />);
+
+  // Act
+  await user.press(screen.getByRole("button", { name: "Increment" }));
+
+  // Assert
+  expect(screen.getByRole("text", { name: "Count: 1" })).toBeOnTheScreen();
+});
+```
+
+### Descriptive Test Names
+
+Use descriptive names that explain the expected behavior:
+
+```typescript
+// Correct - describes behavior
+test("displays validation error when email format is invalid", () => {});
+test("disables submit button while form is submitting", () => {});
+
+// Incorrect - vague or implementation-focused
+test("email validation works", () => {});
+test("sets isSubmitting to true", () => {});
+```
+
+## Jest Configuration
+
+### Manual React Native Resolution (No Preset)
+
+Lisa configures Jest manually instead of using the `jest-expo` preset to avoid
+jsdom incompatibility with `react-native/jest/setup.js`. The configuration in
+`jest.expo.ts` provides haste, resolver, transform, and setupFiles that match
+the preset's behavior without redefining `window`.
+
+### Use Fake Timers with userEvent
+
+```typescript
+jest.useFakeTimers();
+
+test("handles debounced input", async () => {
+  const user = userEvent.setup();
+  render(<SearchInput />);
+
+  await user.type(screen.getByRole("textbox"), "query");
+  jest.runAllTimers();
+
+  expect(await screen.findByText("Results")).toBeOnTheScreen();
+});
+```
+
+## Anti-Patterns
+
+### Never Test Implementation Details
+
+```typescript
+// Wrong - testing internal state
+expect(wrapper.state().isLoading).toBe(true);
+
+// Wrong - testing component methods
+expect(wrapper.instance().handleSubmit).toHaveBeenCalled();
+
+// Correct - testing visible behavior
+expect(screen.getByRole("progressbar")).toBeOnTheScreen();
+```
+
+### Never Use getByTestId as Default
+
+```typescript
+// Wrong - using testID when semantic query exists
+screen.getByTestId("submit-button");
+
+// Correct - using accessible query
+screen.getByRole("button", { name: "Submit" });
+```
+
+### Never Wrap render or fireEvent in act()
+
+```typescript
+// Wrong - unnecessary act wrapper
+await act(async () => {
+  render(<Component />);
+});
+
+// Correct - render already wraps in act
+render(<Component />);
+```
+
+### Never Put Side Effects in waitFor
+
+```typescript
+// Wrong - side effect in waitFor
+await waitFor(() => {
+  fireEvent.press(button);
+  expect(result).toBeOnTheScreen();
+});
+
+// Correct - side effect before waitFor
+fireEvent.press(button);
+await waitFor(() => {
+  expect(result).toBeOnTheScreen();
+});
+```
+
+### Never Use Multiple Assertions in waitFor
+
+```typescript
+// Wrong - multiple assertions
+await waitFor(() => {
+  expect(title).toBeOnTheScreen();
+  expect(subtitle).toBeOnTheScreen();
+  expect(button).toBeEnabled();
+});
+
+// Correct - single assertion, chain with findBy
+expect(await screen.findByRole("heading")).toBeOnTheScreen();
+expect(screen.getByText("Subtitle")).toBeOnTheScreen();
+expect(screen.getByRole("button")).toBeEnabled();
+```
+
+## Quick Reference
+
+### Common Matchers
+
+| Matcher               | Purpose                         |
+| --------------------- | ------------------------------- |
+| `toBeOnTheScreen()`   | Element is currently rendered   |
+| `toBeEnabled()`       | Interactive element is enabled  |
+| `toBeDisabled()`      | Interactive element is disabled |
+| `toHaveTextContent()` | Element contains text           |
+| `toBeVisible()`       | Element is visible to user      |
+| `toBeChecked()`       | Checkbox/radio is checked       |
+
+### Query Variants
+
+| Prefix     | Returns              | Throws on 0 | Throws on >1 | Async |
+| ---------- | -------------------- | ----------- | ------------ | ----- |
+| getBy      | Element              | Yes         | Yes          | No    |
+| queryBy    | Element \| null      | No          | Yes          | No    |
+| findBy     | Promise\<Element\>   | Yes         | Yes          | Yes   |
+| getAllBy   | Element[]            | Yes         | No           | No    |
+| queryAllBy | Element[]            | No          | No           | No    |
+| findAllBy  | Promise\<Element[]\> | Yes         | No           | Yes   |
+
+## References
+
+- [Query Priority](references/query-priority.md) - Detailed query selection guidance
+- [Async Patterns](references/async-patterns.md) - Comprehensive async testing patterns
+- [Mocking Patterns](references/mocking-patterns.md) - Common mocking configurations
+- [Expo Router Testing](references/expo-router-testing.md) - Testing with Expo Router

package/plugins/lisa-expo/.codex-plugin/skills/testing-library/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Testing Library"
+short_description: "Enforces best practices for…"
+default_prompt:
+  - "Use $testing-library: Enforces best practices for…."