doc: llm guidelines

Author: mdjastrzebski

website/docs/14.x/docs/guides/common-mistakes.mdx

@@ -625,15 +625,13 @@ This works fine, but it's more conventional to name it something more descriptiv
 
 The key principles to remember:
 
-1. Use the right query for your use case (prefer `getByRole`)
-2. Use `findBy*` for async elements instead of `waitFor` + `getBy*`
-3. Use `queryBy*` only for checking non-existence
-4. Avoid side-effects in `waitFor`
-5. Use ARIA attributes (`role`, `aria-label`) instead of `accessibility*` props
-6. Use the right assertions (RNTL matchers)
-7. Prefer `screen` over destructuring from `render`
-8. Use `userEvent` for realistic user interactions
-9. Remember that `render`, `fireEvent`, and `renderHook` are async in v14
-10. Don't use `container.queryAll` directly - use proper queries
-
-By following these guidelines, your tests will be more maintainable, accessible, and reliable.
+1. **Use the right query** - Prefer `getByRole` as your first choice, use `findBy*` for async elements, and `queryBy*` only for checking non-existence
+2. **Use proper assertions** - Use RNTL's built-in matchers (`toBeOnTheScreen()`, `toBeDisabled()`, etc.) instead of asserting on props directly
+3. **Handle async operations correctly** - Always `await` `render()`, `fireEvent`, `renderHook`, and `userEvent` methods in v14
+4. **Use `waitFor` correctly** - Avoid side-effects in callbacks, use `findBy*` instead when possible, and keep callbacks focused
+5. **Follow accessibility best practices** - Prefer ARIA attributes (`role`, `aria-label`) over `accessibility*` props
+6. **Organize code well** - Use `screen` over destructuring, prefer `userEvent` over `fireEvent`, and don't use `cleanup()`
+
+For detailed guidelines and examples, see the [LLM Guidelines](llm-guidelines) document.
+
+By following these principles, your tests will be more maintainable, accessible, and reliable.

website/docs/14.x/docs/guides/llm-guidelines.mdx

@@ -0,0 +1,152 @@
+# LLM Guidelines for React Native Testing Library
+
+Actionable guidelines for writing tests with React Native Testing Library (RNTL) v14.
+
+## Query Selection
+
+- **Prefer `getByRole`** as first choice for querying elements
+- **Query priority**: `getByRole` → `getByLabelText` → `getByPlaceholderText` → `getByText` → `getByDisplayValue` → `getByTestId` (last resort)
+- **Use `findBy*`** for elements that appear asynchronously (after API calls, timeouts, state updates)
+- **Use `queryBy*` ONLY** for checking non-existence (with `.not.toBeOnTheScreen()`)
+- **Never use `getBy*`** for non-existence checks
+- **Avoid `container.queryAll()`** - use `screen` queries instead
+- **Query by visible text**, not `testID` when text is available
+
+## Assertions
+
+- **Use RNTL matchers**: `toBeOnTheScreen()`, `toBeDisabled()`, `toHaveTextContent()`, `toHaveAccessibleName()`
+- **Don't assert on props directly** - use semantic matchers instead
+- **Combine queries with matchers**: `expect(screen.getByText('Hello')).toBeOnTheScreen()`
+- **No redundant null checks** - `getBy*` already throws if not found
+
+## Async/Await (v14)
+
+- **Always `await`**: `render()`, `fireEvent.*`, `renderHook()`, `userEvent.*`
+- **Make test functions `async`**: `test('name', async () => { ... })`
+- **Don't wrap in `act()`** - `render` and `fireEvent` handle it internally
+
+## waitFor Usage
+
+- **Use `findBy*`** instead of `waitFor` + `getBy*` when waiting for elements
+- **Never perform side-effects** (like `fireEvent.press()`) inside `waitFor` callbacks
+- **One assertion per `waitFor`** callback
+- **Never pass empty callbacks** - always include a meaningful assertion
+- **Place side-effects before `waitFor`** - perform actions, then wait for result
+
+## Accessibility
+
+- **Prefer ARIA attributes** over `accessibility*` props:
+  - `role` instead of `accessibilityRole`
+  - `aria-label` instead of `accessibilityLabel`
+  - `aria-disabled` instead of `accessibilityState={{ disabled: true }}`
+  - `aria-checked` instead of `accessibilityState={{ checked: true }}`
+  - `aria-selected` instead of `accessibilityState={{ selected: true }}`
+  - `aria-expanded` instead of `accessibilityState={{ expanded: true }}`
+  - `aria-busy` instead of `accessibilityState={{ busy: true }}`
+- **Only add necessary attributes** - don't add unnecessary accessibility props
+- **Use `role` prop** on interactive elements for better querying
+
+## Code Organization
+
+- **Use `screen`** instead of destructuring from `render()`: `screen.getByText()` not `const { getByText } = render()`
+- **Prefer `userEvent`** over `fireEvent` for realistic interactions
+- **Don't use `cleanup()`** - handled automatically
+- **Name wrappers descriptively**: `ThemeProvider` not `Wrapper`
+- **Install ESLint plugin**: `eslint-plugin-testing-library`
+
+## Quick Checklist
+
+- ✅ Using `getByRole` as first choice?
+- ✅ Using `await` for all async operations?
+- ✅ Using `findBy*` for async elements (not `waitFor` + `getBy*`)?
+- ✅ Using `queryBy*` only for non-existence?
+- ✅ Using RNTL matchers (`toBeOnTheScreen()`, `toBeDisabled()`, etc.)?
+- ✅ Using ARIA attributes (`role`, `aria-label`) not `accessibility*` props?
+- ✅ Using `screen` not destructuring from `render()`?
+- ✅ Avoiding side-effects in `waitFor`?
+- ✅ Using `userEvent` when appropriate?
+
+## Example: Good Pattern
+
+```tsx
+import { render, screen } from '@testing-library/react-native';
+import userEvent from '@testing-library/react-native';
+import { Pressable, Text, TextInput, View } from 'react-native';
+
+test('user can submit form', async () => {
+  const user = userEvent.setup();
+  
+  const Component = () => {
+    const [name, setName] = React.useState('');
+    const [submitted, setSubmitted] = React.useState(false);
+    
+    return (
+      <View>
+        <TextInput
+          role="textbox"
+          aria-label="Name"
+          value={name}
+          onChangeText={setName}
+        />
+        <Pressable 
+          role="button" 
+          aria-label="Submit"
+          onPress={() => setSubmitted(true)}
+        >
+          <Text>Submit</Text>
+        </Pressable>
+        {submitted && <Text role="alert">Form submitted!</Text>}
+      </View>
+    );
+  };
+
+  await render(<Component />);
+  
+  // ✅ getByRole as first choice
+  const input = screen.getByRole('textbox', { name: 'Name' });
+  const button = screen.getByRole('button', { name: 'Submit' });
+  
+  // ✅ userEvent for realistic interactions
+  await user.type(input, 'John Doe');
+  await user.press(button);
+  
+  // ✅ findBy* for async elements
+  const successMessage = await screen.findByRole('alert');
+  
+  // ✅ RNTL matchers
+  expect(successMessage).toBeOnTheScreen();
+  expect(successMessage).toHaveTextContent('Form submitted!');
+});
+```
+
+## Example: Anti-Patterns
+
+```tsx
+// ❌ Missing await
+test('bad', () => {
+  render(<Component />);
+  fireEvent.press(screen.getByText('Submit'));
+});
+
+// ❌ getBy* for non-existence
+expect(screen.getByText('Error')).not.toBeOnTheScreen();
+
+// ❌ waitFor + getBy* instead of findBy*
+await waitFor(() => {
+  expect(screen.getByText('Loaded')).toBeOnTheScreen();
+});
+
+// ❌ Side-effect in waitFor
+await waitFor(async () => {
+  await fireEvent.press(button);
+  expect(screen.getByText('Result')).toBeOnTheScreen();
+});
+
+// ❌ accessibility* props instead of ARIA
+<Pressable accessibilityRole="button" accessibilityLabel="Submit" />
+
+// ❌ Destructuring from render
+const { getByText } = await render(<Component />);
+```
+
+By following these guidelines, your tests will be more maintainable, accessible, and reliable.