@ranimontagna/agent-toolkit 0.1.5 → 0.1.6

package/skills/frontend/react/react-testing/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: react-testing
+description: React component testing with React Testing Library, Vitest/Jest, MSW for network mocking, accessibility assertions with axe, and the decision boundary between component tests and Playwright/Cypress end-to-end runs. Use when writing or fixing tests for React components, hooks, or pages.
+origin: ECC
+---
+
+# React Testing
+
+Comprehensive React testing patterns for behavior-focused component tests, custom hook tests, accessibility assertions, and network-level mocking.
+
+## When to Activate
+
+- Writing tests for React components, custom hooks, or pages
+- Adding test coverage to legacy untested components
+- Migrating from Enzyme or class-component-era patterns to React Testing Library
+- Setting up Vitest or Jest for a new React project
+- Mocking HTTP requests in tests
+- Asserting accessibility violations
+- Deciding which tests belong in RTL vs Playwright Component Testing vs full E2E
+
+## Core Principle
+
+Test what the user sees and does, not implementation details.
+
+A test should:
+
+- Render the component with the same providers it has in production
+- Interact with it via accessible queries (role, label) and `userEvent`
+- Assert visible output and observable side effects (callback fired, request sent)
+
+A test should NOT:
+
+- Inspect component state, props passed to children, or which hooks were called
+- Mock React itself or framework hooks
+- Assert on the number of renders or DOM structure beyond what affects users
+
+## Library Choice
+
+| Runner | When | Note |
+|---|---|---|
+| **Vitest** | Vite, Remix, modern setups | Faster, native ESM, Jest-compatible API |
+| **Jest** | Next.js, CRA, established repos | Default for many React projects |
+| **Playwright Component Testing** | Real browser engine needed | Use when JSDOM lacks the required feature |
+| **Cypress Component Testing** | Real browser, Cypress already in use | Alternative to Playwright CT |
+
+Pick one. Do not run RTL + Vitest AND Playwright CT in the same repo unless you have a clear lane separation.
+
+## Query Priority
+
+React Testing Library exposes queries in three tiers — use top-down:
+
+1. **Accessible to everyone**: `getByRole`, `getByLabelText`, `getByPlaceholderText`, `getByText`, `getByDisplayValue`
+2. **Semantic**: `getByAltText`, `getByTitle`
+3. **Test IDs (escape hatch)**: `getByTestId`
+
+```tsx
+// Best
+screen.getByRole("button", { name: /save/i });
+
+// OK for inputs
+screen.getByLabelText("Email");
+
+// Last resort
+screen.getByTestId("save-btn");
+```
+
+Variants:
+
+- `getBy*` — throws if no match
+- `queryBy*` — returns `null` (use for "assert absence")
+- `findBy*` — async, returns a Promise (use for elements that appear after async work)
+
+## User Interaction with `userEvent`
+
+```tsx
+import userEvent from "@testing-library/user-event";
+
+test("submits the form", async () => {
+  const user = userEvent.setup();
+  const onSubmit = vi.fn();
+  render(<UserForm onSubmit={onSubmit} />);
+
+  await user.type(screen.getByLabelText("Email"), "user@example.com");
+  await user.click(screen.getByRole("button", { name: /save/i }));
+
+  expect(onSubmit).toHaveBeenCalledWith({ email: "user@example.com" });
+});
+```
+
+- Always `await` userEvent calls
+- Call `userEvent.setup()` once per test, reuse the returned `user`
+- `userEvent` simulates a real browser sequence; `fireEvent` dispatches a single synthetic event — prefer `userEvent`
+
+## Async Patterns
+
+```tsx
+// Element that appears after async work
+expect(await screen.findByText("Loaded")).toBeInTheDocument();
+
+// Side effect assertion
+await waitFor(() => expect(saveSpy).toHaveBeenCalled());
+
+// Element that should disappear
+await waitForElementToBeRemoved(() => screen.queryByText("Loading"));
+```
+
+Never `setTimeout` + assertion — flaky. Use the matchers above.
+
+## Network Mocking with MSW
+
+Mock Service Worker mocks at the network layer. The component, hooks, and fetch library all behave exactly as in production.
+
+### Setup
+
+```ts
+// test/setup.ts
+import { setupServer } from "msw/node";
+import { http, HttpResponse } from "msw";
+
+export const handlers = [
+  http.get("/api/users/:id", ({ params }) =>
+    HttpResponse.json({ id: params.id, name: "Alice" }),
+  ),
+  http.post("/api/users", async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: "new-id", ...body }, { status: 201 });
+  }),
+];
+
+export const server = setupServer(...handlers);
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+Configure `onUnhandledRequest: "error"` so any unmocked request fails the test loudly — silent passes are worse than red.
+
+### Per-test override
+
+```tsx
+test("renders error on 500", async () => {
+  server.use(
+    http.get("/api/users/:id", () => new HttpResponse(null, { status: 500 })),
+  );
+  render(<UserPage id="1" />);
+  expect(await screen.findByText(/something went wrong/i)).toBeInTheDocument();
+});
+```
+
+## Provider Wrapping
+
+Wrap providers once in a `test-utils.tsx`:
+
+```tsx
+// test-utils.tsx
+import { render, RenderOptions } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+export function renderWithProviders(
+  ui: React.ReactElement,
+  options?: RenderOptions,
+) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider theme={lightTheme}>
+        <MemoryRouter>{ui}</MemoryRouter>
+      </ThemeProvider>
+    </QueryClientProvider>,
+    options,
+  );
+}
+
+export * from "@testing-library/react";
+```
+
+Then `import { renderWithProviders, screen } from "test-utils"` in every test file.
+
+## Custom Hook Testing
+
+```tsx
+import { renderHook, act } from "@testing-library/react";
+
+test("useCounter increments and decrements", () => {
+  const { result } = renderHook(() => useCounter(0));
+
+  expect(result.current.count).toBe(0);
+
+  act(() => result.current.increment());
+  expect(result.current.count).toBe(1);
+
+  act(() => result.current.decrement());
+  expect(result.current.count).toBe(0);
+});
+
+test("useCounter accepts initial value", () => {
+  const { result } = renderHook(() => useCounter(10));
+  expect(result.current.count).toBe(10);
+});
+
+test("useUser fetches user data", async () => {
+  // Instantiate QueryClient ONCE per test outside the wrapper so it survives re-renders.
+  // Creating it inside the wrapper closure resets cache state on every render, producing flaky tests.
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  const { result } = renderHook(() => useUser("1"), { wrapper });
+
+  await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  expect(result.current.data).toEqual({ id: "1", name: "Alice" });
+});
+```
+
+- Wrap state-changing calls in `act`
+- Test through the hook's public API only
+- For hooks that use context, pass a `wrapper`
+
+## Accessibility Assertions
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"; // or vitest-axe
+expect.extend(toHaveNoViolations);
+
+test("UserCard has no a11y violations", async () => {
+  const { container } = render(<UserCard user={mockUser} />);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+Run axe in component tests for every interactive component. Catches:
+
+- Missing labels on form inputs
+- Invalid ARIA usage
+- Poor color contrast (limited — JSDOM has no real CSS engine, so this works for inline styles only; visual contrast belongs in Playwright)
+- Missing alt text on images
+- Heading order violations
+
+Cross-link: [skills/accessibility/SKILL.md](../accessibility/SKILL.md) for the broader a11y testing playbook.
+
+## When NOT to Use Snapshot Tests
+
+Snapshots of rendered output:
+
+- Break on every styling change
+- Get rubber-stamped during review
+- Test implementation detail (DOM structure), not behavior
+
+Acceptable snapshot uses:
+
+- Pure data serialization functions (`formatInvoice(invoice)` -> stable string)
+- Generated config files (e.g., webpack config output)
+
+For visual regression on components, use Playwright/Cypress screenshots or Percy/Chromatic — actual visual diffs, not DOM strings.
+
+## When to Reach for Playwright / Cypress
+
+JSDOM (used by Vitest/Jest) cannot:
+
+- Render real layout (flexbox, grid, viewport queries)
+- Run native browser animation, CSS transitions
+- Test scrolling behavior, drag-and-drop, paste from clipboard
+- Handle iframes, popups, downloads, cross-origin flows
+- Run real network in a controlled environment with full DevTools support
+
+For any of those, use Playwright Component Testing (component test in real browser) or full E2E. See [e2e-testing skill](../e2e-testing/SKILL.md).
+
+Decision boundary:
+
+- A hook, a presentational component, a form with logic -> RTL
+- A component whose layout matters or that uses browser APIs not in JSDOM -> Playwright CT
+- A full user flow across multiple pages -> Playwright/Cypress E2E
+
+## Coverage Targets
+
+| Layer | Target |
+|---|---|
+| Pure utilities | >=90% |
+| Custom hooks | >=85% |
+| Presentational components | >=80% — behavior, not lines |
+| Container components | >=70% — golden paths + error states |
+| Pages | E2E covered separately; smoke test minimum |
+
+Configure via `vitest.config.ts` / `jest.config.js`:
+
+```ts
+// vitest.config.ts
+test: {
+  coverage: {
+    provider: "v8",
+    reporter: ["text", "html", "lcov"],
+    thresholds: {
+      lines: 80,
+      functions: 80,
+      branches: 70,
+      statements: 80,
+    },
+  },
+}
+```
+
+## Anti-Patterns
+
+- `container.querySelector("...")` — bypasses accessibility queries, lets tests pass when real users would fail
+- Asserting on number of renders — implementation detail
+- `jest.mock("react", ...)` — never mock React. Refactor the component instead
+- Mocking child components by default — tests the integration, not isolation. Mock only when the child has heavy side effects
+- Ignoring `act()` warnings — they signal real bugs (state update after unmount, missing async wrapping)
+- Sharing mutable state across tests — flakes when test order changes
+- Tests that pass with `it.skip()` removed — your test does not actually assert what you think
+
+## TDD Workflow
+
+```
+RED     -> Write failing test for the next requirement
+GREEN   -> Write minimal component code to pass
+REFACTOR -> Improve the component, tests stay green
+REPEAT  -> Next requirement
+```
+
+For new components:
+
+1. Define the component's prop type and signature
+2. Write the first test for the simplest case
+3. Verify it fails for the right reason
+4. Implement just enough to pass
+5. Add the next test case
+6. Refactor when the third similar test reveals a pattern
+
+## Test Commands
+
+```bash
+# Vitest
+vitest                            # watch
+vitest run                        # one-shot
+vitest run --coverage             # with coverage
+vitest run path/to/file.test.tsx  # single file
+
+# Jest
+jest --watch
+jest --coverage
+jest path/to/file.test.tsx
+
+# CI mode
+CI=true vitest run --coverage
+```
+
+## Related
+
+- Rules: [rules/react/testing.md](../../rules/react/testing.md)
+- Skills: [react-patterns](../react-patterns/SKILL.md), [accessibility](../accessibility/SKILL.md), [e2e-testing](../e2e-testing/SKILL.md), [tdd-workflow](../tdd-workflow/SKILL.md)
+- Agents: `react-reviewer` (reviews test quality during code review), `tdd-guide` (enforces TDD process)
+- Commands: `/react-test`, `/react-review`
+
+## Examples
+
+### Form submission with MSW and userEvent
+
+```tsx
+test("submits user form and shows success", async () => {
+  server.use(
+    http.post("/api/users", () =>
+      HttpResponse.json({ id: "1", name: "Alice" }, { status: 201 }),
+    ),
+  );
+
+  const user = userEvent.setup();
+  renderWithProviders(<UserForm />);
+
+  await user.type(screen.getByLabelText("Name"), "Alice");
+  await user.type(screen.getByLabelText("Email"), "alice@example.com");
+  await user.click(screen.getByRole("button", { name: /save/i }));
+
+  expect(await screen.findByText(/saved successfully/i)).toBeInTheDocument();
+});
+```
+
+### Testing an error boundary
+
+```tsx
+function Broken() {
+  throw new Error("boom");
+}
+
+test("error boundary renders fallback", () => {
+  // Suppress React's console.error noise for the expected throw, then restore so
+  // the spy does not leak across tests and hide real errors elsewhere.
+  const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  try {
+    render(
+      <ErrorBoundary fallback={<div>Something went wrong</div>}>
+        <Broken />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText("Something went wrong")).toBeInTheDocument();
+  } finally {
+    errorSpy.mockRestore();
+  }
+});
+```
+
+### Testing a Suspense boundary
+
+```tsx
+test("shows loading then content", async () => {
+  renderWithProviders(
+    <Suspense fallback={<div>Loading...</div>}>
+      <UserDetail id="1" />
+    </Suspense>,
+  );
+
+  expect(screen.getByText("Loading...")).toBeInTheDocument();
+  expect(await screen.findByText("Alice")).toBeInTheDocument();
+});
+```

package/skills/frontend/react-native/react-native-expert/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/frontend/react-native/react-native-expert/NOTICE.md

@@ -0,0 +1,11 @@
+# Attribution
+
+This skill is copied from Jeffallan's public `Jeffallan/claude-skills` repository.
+
+- Source: https://github.com/Jeffallan/claude-skills/tree/main/skills/react-native-expert
+- Imported from commit: `e8be415bc94d8d6ebddc2fb50e5d03c6e27d4319`
+- Upstream skill name: `react-native-expert`
+- License: MIT
+- Copyright: Copyright (c) 2025
+
+The upstream MIT license text is preserved in `LICENSE`.

package/skills/frontend/react-native/react-native-expert/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: react-native-expert
+description: Builds, optimizes, and debugs cross-platform mobile applications with React Native and Expo. Implements navigation hierarchies (tabs, stacks, drawers), configures native modules, optimizes FlatList rendering with memo and useCallback, and handles platform-specific code for iOS and Android. Use when building a React Native or Expo mobile app, setting up navigation, integrating native modules, improving scroll performance, handling SafeArea or keyboard input, or configuring Expo SDK projects.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: frontend
+  triggers: React Native, Expo, mobile app, iOS, Android, cross-platform, native module
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: react-expert, flutter-expert, test-master
+---
+
+# React Native Expert
+
+Senior mobile engineer building production-ready cross-platform applications with React Native and Expo.
+
+## Core Workflow
+
+1. **Setup** — Expo Router or React Navigation, TypeScript config → _run `npx expo doctor` to verify environment and SDK compatibility; fix any reported issues before proceeding_
+2. **Structure** — Feature-based organization
+3. **Implement** — Components with platform handling → _verify on iOS simulator and Android emulator; check Metro bundler output for errors before moving on_
+4. **Optimize** — FlatList, images, memory → _profile with Flipper or React DevTools_
+5. **Test** — Both platforms, real devices
+
+### Error Recovery
+- **Metro bundler errors** → clear cache with `npx expo start --clear`, then restart
+- **iOS build fails** → check Xcode logs → resolve native dependency or provisioning issue → rebuild with `npx expo run:ios`
+- **Android build fails** → check `adb logcat` or Gradle output → resolve SDK/NDK version mismatch → rebuild with `npx expo run:android`
+- **Native module not found** → run `npx expo install <module>` to ensure compatible version, then rebuild native layers
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Navigation | `references/expo-router.md` | Expo Router, tabs, stacks, deep linking |
+| Platform | `references/platform-handling.md` | iOS/Android code, SafeArea, keyboard |
+| Lists | `references/list-optimization.md` | FlatList, performance, memo |
+| Storage | `references/storage-hooks.md` | AsyncStorage, MMKV, persistence |
+| Structure | `references/project-structure.md` | Project setup, architecture |
+
+## Constraints
+
+### MUST DO
+- Use FlatList/SectionList for lists (not ScrollView)
+- Implement memo + useCallback for list items
+- Handle SafeAreaView for notches
+- Test on both iOS and Android real devices
+- Use KeyboardAvoidingView for forms
+- Handle Android back button in navigation
+
+### MUST NOT DO
+- Use ScrollView for large lists
+- Use inline styles extensively (creates new objects)
+- Hardcode dimensions (use Dimensions API or flex)
+- Ignore memory leaks from subscriptions
+- Skip platform-specific testing
+- Use waitFor/setTimeout for animations (use Reanimated)
+
+## Code Examples
+
+### Optimized FlatList with memo + useCallback
+
+```tsx
+import React, { memo, useCallback } from 'react';
+import { FlatList, View, Text, StyleSheet } from 'react-native';
+
+type Item = { id: string; title: string };
+
+const ListItem = memo(({ title, onPress }: { title: string; onPress: () => void }) => (
+  <View style={styles.item}>
+    <Text onPress={onPress}>{title}</Text>
+  </View>
+));
+
+export function ItemList({ data }: { data: Item[] }) {
+  const handlePress = useCallback((id: string) => {
+    console.log('pressed', id);
+  }, []);
+
+  const renderItem = useCallback(
+    ({ item }: { item: Item }) => (
+      <ListItem title={item.title} onPress={() => handlePress(item.id)} />
+    ),
+    [handlePress]
+  );
+
+  return (
+    <FlatList
+      data={data}
+      keyExtractor={(item) => item.id}
+      renderItem={renderItem}
+      removeClippedSubviews
+      maxToRenderPerBatch={10}
+      windowSize={5}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  item: { padding: 16, borderBottomWidth: StyleSheet.hairlineWidth },
+});
+```
+
+### KeyboardAvoidingView Form
+
+```tsx
+import React from 'react';
+import {
+  KeyboardAvoidingView,
+  Platform,
+  ScrollView,
+  TextInput,
+  StyleSheet,
+  SafeAreaView,
+} from 'react-native';
+
+export function LoginForm() {
+  return (
+    <SafeAreaView style={styles.safe}>
+      <KeyboardAvoidingView
+        style={styles.flex}
+        behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+      >
+        <ScrollView contentContainerStyle={styles.content} keyboardShouldPersistTaps="handled">
+          <TextInput style={styles.input} placeholder="Email" autoCapitalize="none" />
+          <TextInput style={styles.input} placeholder="Password" secureTextEntry />
+        </ScrollView>
+      </KeyboardAvoidingView>
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  safe: { flex: 1 },
+  flex: { flex: 1 },
+  content: { padding: 16, gap: 12 },
+  input: { borderWidth: 1, borderRadius: 8, padding: 12, fontSize: 16 },
+});
+```
+
+### Platform-Specific Component
+
+```tsx
+import { Platform, StyleSheet, View, Text } from 'react-native';
+
+export function StatusChip({ label }: { label: string }) {
+  return (
+    <View style={styles.chip}>
+      <Text style={styles.label}>{label}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  chip: {
+    paddingHorizontal: 12,
+    paddingVertical: 4,
+    borderRadius: 999,
+    backgroundColor: '#0a7ea4',
+    // Platform-specific shadow
+    ...Platform.select({
+      ios: { shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.2, shadowRadius: 4 },
+      android: { elevation: 3 },
+    }),
+  },
+  label: { color: '#fff', fontSize: 13, fontWeight: '600' },
+});
+```
+
+## Output Format
+
+When implementing React Native features, deliver:
+1. **Component code** — TypeScript, with prop types defined
+2. **Platform handling** — `Platform.select` or `.ios.tsx` / `.android.tsx` splits as needed
+3. **Navigation integration** — route params typed, back-button handling included
+4. **Performance notes** — memo boundaries, key extractor strategy, image caching
+
+## Knowledge Reference
+
+React Native 0.73+, Expo SDK 50+, Expo Router, React Navigation 7, Reanimated 3, Gesture Handler, AsyncStorage, MMKV, React Query, Zustand
+
+[Documentation](https://jeffallan.github.io/claude-skills/skills/frontend/react-native-expert/)