autoworkflow 3.1.5 → 3.5.0

package/.claude/skills/testing-library.md

@@ -0,0 +1,371 @@
+# Testing Library Skill
+
+## Basic Test Structure
+\`\`\`typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { vi, expect, test, describe, beforeEach } from 'vitest';
+import { LoginForm } from './LoginForm';
+
+describe('LoginForm', () => {
+  const mockOnSubmit = vi.fn();
+
+  beforeEach(() => {
+    mockOnSubmit.mockClear();
+  });
+
+  test('submits form with valid data', async () => {
+    const user = userEvent.setup();
+
+    render(<LoginForm onSubmit={mockOnSubmit} />);
+
+    // Query by accessible role/label
+    await user.type(screen.getByLabelText('Email'), 'test@example.com');
+    await user.type(screen.getByLabelText('Password'), 'password123');
+    await user.click(screen.getByRole('button', { name: 'Sign in' }));
+
+    expect(mockOnSubmit).toHaveBeenCalledWith({
+      email: 'test@example.com',
+      password: 'password123',
+    });
+  });
+
+  test('shows validation error for invalid email', async () => {
+    const user = userEvent.setup();
+
+    render(<LoginForm onSubmit={mockOnSubmit} />);
+
+    await user.type(screen.getByLabelText('Email'), 'invalid-email');
+    await user.click(screen.getByRole('button', { name: 'Sign in' }));
+
+    expect(screen.getByRole('alert')).toHaveTextContent('Invalid email');
+    expect(mockOnSubmit).not.toHaveBeenCalled();
+  });
+});
+\`\`\`
+
+## Queries (Priority Order)
+
+### 1. Accessible Queries (Preferred)
+\`\`\`typescript
+// By role (best - tests accessibility)
+screen.getByRole('button', { name: 'Submit' });
+screen.getByRole('textbox', { name: 'Email' });
+screen.getByRole('checkbox', { name: 'Remember me' });
+screen.getByRole('link', { name: 'Sign up' });
+screen.getByRole('heading', { name: 'Welcome', level: 1 });
+screen.getByRole('list');
+screen.getByRole('listitem');
+screen.getByRole('dialog');
+screen.getByRole('alert');
+screen.getByRole('navigation');
+screen.getByRole('combobox'); // Select/dropdown
+
+// By label (form elements)
+screen.getByLabelText('Email');
+screen.getByLabelText(/email/i);  // Regex
+
+// By placeholder (when no label)
+screen.getByPlaceholderText('Enter your email');
+
+// By text (non-interactive elements)
+screen.getByText('Welcome to our app');
+screen.getByText(/welcome/i);  // Case-insensitive
+\`\`\`
+
+### 2. Semantic Queries
+\`\`\`typescript
+// By alt text (images)
+screen.getByAltText('Company logo');
+
+// By title attribute
+screen.getByTitle('Close');
+
+// By display value (inputs)
+screen.getByDisplayValue('john@example.com');
+\`\`\`
+
+### 3. Test IDs (Last Resort)
+\`\`\`typescript
+// When accessibility isn't possible
+screen.getByTestId('custom-element');
+// Requires: data-testid="custom-element" in JSX
+\`\`\`
+
+## Query Variants
+\`\`\`typescript
+// getBy - throws if not found (single element)
+screen.getByRole('button');
+
+// queryBy - returns null if not found (for asserting absence)
+expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+
+// findBy - async, waits for element (returns Promise)
+await screen.findByRole('alert');
+
+// getAllBy - multiple elements (throws if none)
+screen.getAllByRole('listitem');
+
+// queryAllBy - multiple elements (empty array if none)
+screen.queryAllByRole('listitem');
+
+// findAllBy - async, multiple elements
+await screen.findAllByRole('listitem');
+\`\`\`
+
+## userEvent (Interactions)
+\`\`\`typescript
+import userEvent from '@testing-library/user-event';
+
+// Always setup userEvent
+const user = userEvent.setup();
+
+// Click
+await user.click(element);
+await user.dblClick(element);
+await user.tripleClick(element);  // Select all text
+
+// Type
+await user.type(input, 'Hello World');
+await user.type(input, 'Hello{Enter}');  // Special keys
+await user.clear(input);
+
+// Special keys: {Enter}, {Escape}, {Backspace}, {Delete}, {Tab}
+// Modifiers: {Shift>}A{/Shift} (shift+A)
+
+// Keyboard shortcuts
+await user.keyboard('{Control>}a{/Control}');  // Ctrl+A
+await user.keyboard('{Shift>}{Enter}{/Shift}');  // Shift+Enter
+
+// Select options
+await user.selectOptions(select, 'option-value');
+await user.selectOptions(select, ['value1', 'value2']);  // Multi-select
+
+// Checkbox/Radio
+await user.click(checkbox);  // Toggle
+
+// Hover
+await user.hover(element);
+await user.unhover(element);
+
+// Tab navigation
+await user.tab();
+await user.tab({ shift: true });  // Shift+Tab
+
+// Clipboard
+await user.copy();
+await user.cut();
+await user.paste('pasted text');
+
+// File upload
+const file = new File(['content'], 'file.png', { type: 'image/png' });
+await user.upload(fileInput, file);
+await user.upload(fileInput, [file1, file2]);
+\`\`\`
+
+## Async Utilities
+\`\`\`typescript
+import { render, screen, waitFor, waitForElementToBeRemoved } from '@testing-library/react';
+
+// findBy - built-in waiting
+const alert = await screen.findByRole('alert');
+
+// waitFor - custom condition
+await waitFor(() => {
+  expect(screen.getByText('Loaded')).toBeInTheDocument();
+});
+
+// waitFor with options
+await waitFor(
+  () => expect(mockFn).toHaveBeenCalled(),
+  { timeout: 5000, interval: 100 }
+);
+
+// Wait for element removal
+await waitForElementToBeRemoved(() => screen.queryByText('Loading...'));
+
+// Or with findBy variant
+await waitForElementToBeRemoved(screen.queryByText('Loading...'));
+\`\`\`
+
+## Custom Matchers (jest-dom)
+\`\`\`typescript
+import '@testing-library/jest-dom';
+
+// Visibility
+expect(element).toBeVisible();
+expect(element).not.toBeVisible();
+expect(element).toBeInTheDocument();
+
+// Form states
+expect(input).toBeEnabled();
+expect(input).toBeDisabled();
+expect(input).toBeRequired();
+expect(input).toBeValid();
+expect(input).toBeInvalid();
+expect(checkbox).toBeChecked();
+expect(input).toHaveFocus();
+
+// Content
+expect(element).toHaveTextContent('Hello');
+expect(element).toHaveTextContent(/hello/i);
+expect(input).toHaveValue('test@example.com');
+expect(input).toHaveDisplayValue('test@example.com');
+expect(element).toBeEmptyDOMElement();
+
+// Attributes
+expect(element).toHaveAttribute('href', '/home');
+expect(element).toHaveClass('btn-primary');
+expect(element).toHaveStyle({ color: 'red' });
+
+// Accessibility
+expect(element).toHaveAccessibleName('Submit');
+expect(element).toHaveAccessibleDescription('Submit the form');
+\`\`\`
+
+## Testing with Context/Providers
+\`\`\`typescript
+import { render } from '@testing-library/react';
+import { ThemeProvider } from './ThemeContext';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+// Custom render with providers
+function customRender(ui: React.ReactElement, options = {}) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ThemeProvider>
+          {children}
+        </ThemeProvider>
+      </QueryClientProvider>
+    );
+  }
+
+  return render(ui, { wrapper: Wrapper, ...options });
+}
+
+// Usage
+import { customRender as render } from '../test-utils';
+
+test('renders with theme', () => {
+  render(<MyComponent />);
+  // Component has access to all providers
+});
+\`\`\`
+
+## Testing Hooks
+\`\`\`typescript
+import { renderHook, act } from '@testing-library/react';
+import { useCounter } from './useCounter';
+
+test('should increment counter', () => {
+  const { result } = renderHook(() => useCounter());
+
+  expect(result.current.count).toBe(0);
+
+  act(() => {
+    result.current.increment();
+  });
+
+  expect(result.current.count).toBe(1);
+});
+
+// With initial props
+test('should start with initial value', () => {
+  const { result, rerender } = renderHook(
+    ({ initialCount }) => useCounter(initialCount),
+    { initialProps: { initialCount: 10 } }
+  );
+
+  expect(result.current.count).toBe(10);
+
+  // Re-render with new props
+  rerender({ initialCount: 20 });
+});
+
+// Async hooks
+test('should fetch data', async () => {
+  const { result } = renderHook(() => useFetchUser('123'));
+
+  expect(result.current.loading).toBe(true);
+
+  await waitFor(() => {
+    expect(result.current.loading).toBe(false);
+  });
+
+  expect(result.current.data).toEqual({ id: '123', name: 'John' });
+});
+\`\`\`
+
+## Debugging
+\`\`\`typescript
+import { screen, prettyDOM } from '@testing-library/react';
+
+// Print DOM to console
+screen.debug();  // Entire document
+screen.debug(element);  // Specific element
+screen.debug(element, 20000);  // Increase max length
+
+// Get pretty DOM string
+console.log(prettyDOM(element));
+
+// Log testing playground URL
+screen.logTestingPlaygroundURL();
+
+// Configure debug output
+import { configure } from '@testing-library/react';
+configure({ defaultHidden: true });  // Show hidden elements
+\`\`\`
+
+## Setup File (vitest.setup.ts)
+\`\`\`typescript
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import { afterEach, vi } from 'vitest';
+
+// Cleanup after each test
+afterEach(() => {
+  cleanup();
+});
+
+// Mock window.matchMedia
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: vi.fn().mockImplementation((query) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  })),
+});
+
+// Mock IntersectionObserver
+class MockIntersectionObserver {
+  observe = vi.fn();
+  disconnect = vi.fn();
+  unobserve = vi.fn();
+}
+window.IntersectionObserver = MockIntersectionObserver as any;
+\`\`\`
+
+## ❌ DON'T
+- Use \`getByTestId\` when accessible queries work
+- Use \`fireEvent\` when \`userEvent\` works
+- Test implementation details (state, props, methods)
+- Test third-party library internals
+- Use arbitrary waits (\`setTimeout\`)
+- Query by class or ID
+
+## ✅ DO
+- Query by role, label, text (accessibility first)
+- Use \`userEvent\` for interactions
+- Test from user's perspective
+- Use \`findBy\` for async elements
+- Use \`queryBy\` to assert absence
+- Create custom render with providers
+- Use \`screen\` for queries (not destructured render)