gaia-framework 1.57.0 → 1.57.2

package/_gaia/testing/knowledge/mobile-testing/appium-patterns.md

@@ -1,164 +0,0 @@
----
-name: appium-patterns
-tier: mobile-testing
-version: '1.0'
----
-
-# Appium Patterns
-
-## Principle
-
-Appium provides cross-platform mobile test automation using the WebDriver protocol.
-Write tests once against a standard API, then run them on iOS and Android with
-platform-specific capabilities. The Page Object Model keeps tests maintainable
-as the app evolves.
-
-## Rationale
-
-Native mobile apps have platform-specific UI frameworks (UIKit, Jetpack Compose) that
-require different automation approaches. Appium abstracts these differences behind a
-unified API, enabling shared test logic with platform-specific configuration. This
-reduces maintenance overhead for cross-platform apps.
-
-## Pattern Examples
-
-### Desired Capabilities
-
-```javascript
-// Android
-const androidCaps = {
-  platformName: 'Android',
-  'appium:automationName': 'UiAutomator2',
-  'appium:deviceName': 'Pixel 6',
-  'appium:platformVersion': '13',
-  'appium:app': '/path/to/app.apk',
-  'appium:noReset': false,
-};
-
-// iOS
-const iosCaps = {
-  platformName: 'iOS',
-  'appium:automationName': 'XCUITest',
-  'appium:deviceName': 'iPhone 14',
-  'appium:platformVersion': '16.4',
-  'appium:app': '/path/to/app.ipa',
-  'appium:noReset': false,
-};
-```
-
-### Element Location Strategies
-
-```javascript
-// Accessibility ID — preferred, cross-platform
-const loginButton = await driver.$('~login-button');
-
-// Resource ID (Android)
-const emailField = await driver.$('android=new UiSelector().resourceId("email-input")');
-
-// iOS predicate
-const submitBtn = await driver.$('-ios predicate string:name == "Submit"');
-
-// XPath — last resort, fragile
-const header = await driver.$('//android.widget.TextView[@text="Welcome"]');
-```
-
-### Page Object Model
-
-```typescript
-class LoginPage {
-  get emailInput() { return $('~email-input'); }
-  get passwordInput() { return $('~password-input'); }
-  get loginButton() { return $('~login-button'); }
-  get errorMessage() { return $('~error-message'); }
-
-  async login(email: string, password: string) {
-    await this.emailInput.setValue(email);
-    await this.passwordInput.setValue(password);
-    await this.loginButton.click();
-  }
-
-  async getErrorText(): Promise<string> {
-    await this.errorMessage.waitForDisplayed({ timeout: 5000 });
-    return this.errorMessage.getText();
-  }
-}
-```
-
-### Wait Strategies
-
-```javascript
-// Explicit wait — preferred
-await driver.waitUntil(
-  async () => (await $('~dashboard-title')).isDisplayed(),
-  { timeout: 10000, timeoutMsg: 'Dashboard did not load' }
-);
-
-// Element wait
-const element = await $('~loading-spinner');
-await element.waitForDisplayed({ timeout: 5000, reverse: true }); // wait to disappear
-```
-
-### Gesture Automation
-
-```javascript
-// Swipe
-await driver.execute('mobile: swipe', { direction: 'up', element: listView.elementId });
-
-// Long press
-await driver.execute('mobile: longClickGesture', {
-  elementId: item.elementId,
-  duration: 2000,
-});
-
-// Scroll to element
-await driver.execute('mobile: scroll', {
-  strategy: 'accessibility id',
-  selector: 'target-element',
-});
-```
-
-### Device Farm Integration
-
-```javascript
-// BrowserStack
-const bsCaps = {
-  'bstack:options': {
-    projectName: 'MyApp Tests',
-    buildName: `Build ${process.env.BUILD_NUMBER}`,
-    deviceName: 'Samsung Galaxy S22',
-    osVersion: '12.0',
-  },
-};
-
-// SauceLabs
-const sauceCaps = {
-  'sauce:options': {
-    appiumVersion: '2.0',
-    deviceName: 'Google Pixel 6',
-    platformVersion: '13',
-  },
-};
-```
-
-## Anti-Patterns
-
-1. **XPath-first selectors** — XPath is slow and fragile. Use accessibility IDs
-   as the primary locator strategy; they survive UI restructuring.
-
-2. **Implicit waits** — Global implicit waits mask timing issues and slow down
-   failure detection. Use explicit waits targeted to specific elements.
-
-3. **Hardcoded sleep** — `Thread.sleep(5000)` is always wrong. Use waitUntil
-   with a meaningful condition and timeout.
-
-4. **Platform-coupled tests** — Writing separate test suites for iOS and Android
-   when 90% of the logic is identical. Share test logic, isolate capabilities.
-
-5. **Ignoring app state** — Not resetting app state between tests causes cascading
-   failures. Use `noReset: false` or explicit cleanup.
-
-## Integration Points
-
-- **Tools**: Appium Server 2.x, UiAutomator2 (Android), XCUITest (iOS)
-- **Workflows**: `mobile-testing` (test plan), `test-automation` (coverage expansion)
-- **Related fragments**: `selector-resilience` (locator strategies)

package/_gaia/testing/knowledge/mobile-testing/react-native-testing.md

@@ -1,193 +0,0 @@
----
-name: react-native-testing
-tier: mobile-testing
-version: '1.0'
----
-
-# React Native Testing
-
-## Principle
-
-React Native testing follows the same test pyramid as web React: Jest for unit tests,
-React Native Testing Library for component tests, and Detox for E2E. Native modules
-require mocking, but the core testing philosophy — test behavior, not implementation
-— remains identical.
-
-## Rationale
-
-React Native bridges JavaScript and native code, creating unique testing challenges.
-Native modules, platform-specific behavior, and navigation require careful mocking
-strategies. Detox provides gray-box E2E testing that synchronizes with the app's
-internal state, reducing flakiness.
-
-## Pattern Examples
-
-### Jest + React Native Testing Library
-
-```typescript
-import { render, screen, fireEvent } from '@testing-library/react-native';
-import { ProfileCard } from './ProfileCard';
-
-describe('ProfileCard', () => {
-  it('displays user information', () => {
-    render(<ProfileCard name="Alice" email="alice@example.com" />);
-
-    expect(screen.getByText('Alice')).toBeTruthy();
-    expect(screen.getByText('alice@example.com')).toBeTruthy();
-  });
-
-  it('calls onPress when tapped', () => {
-    const onPress = jest.fn();
-    render(<ProfileCard name="Alice" email="alice@example.com" onPress={onPress} />);
-
-    fireEvent.press(screen.getByText('Alice'));
-    expect(onPress).toHaveBeenCalledTimes(1);
-  });
-});
-```
-
-### Navigation Testing
-
-```typescript
-import { NavigationContainer } from '@react-navigation/native';
-import { render, screen, fireEvent } from '@testing-library/react-native';
-
-function renderWithNavigation(component: React.ReactElement) {
-  return render(
-    <NavigationContainer>{component}</NavigationContainer>
-  );
-}
-
-describe('AppNavigator', () => {
-  it('navigates to profile on tab press', () => {
-    renderWithNavigation(<AppNavigator />);
-    fireEvent.press(screen.getByText('Profile'));
-    expect(screen.getByText('Profile Settings')).toBeTruthy();
-  });
-});
-```
-
-### Native Module Mocking
-
-```typescript
-// jest/setup.ts — mock native modules globally
-jest.mock('react-native/Libraries/Animated/NativeAnimatedHelper');
-
-jest.mock('@react-native-async-storage/async-storage', () =>
-  require('@react-native-async-storage/async-storage/jest/async-storage-mock')
-);
-
-jest.mock('react-native-camera', () => ({
-  RNCamera: {
-    Constants: {
-      Type: { back: 'back', front: 'front' },
-      FlashMode: { on: 'on', off: 'off', auto: 'auto' },
-    },
-  },
-}));
-
-// Platform-specific mock
-jest.mock('react-native/Libraries/Utilities/Platform', () => ({
-  OS: 'ios',
-  select: (obj: any) => obj.ios,
-}));
-```
-
-### Detox E2E Setup
-
-```javascript
-// .detoxrc.js
-module.exports = {
-  testRunner: { args: { config: 'e2e/jest.config.js' } },
-  apps: {
-    'ios.release': {
-      type: 'ios.app',
-      binaryPath: 'ios/build/MyApp.app',
-      build: 'xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphonesimulator',
-    },
-    'android.release': {
-      type: 'android.apk',
-      binaryPath: 'android/app/build/outputs/apk/release/app-release.apk',
-      build: 'cd android && ./gradlew assembleRelease',
-    },
-  },
-  devices: {
-    simulator: { type: 'ios.simulator', device: { type: 'iPhone 15' } },
-    emulator: { type: 'android.emulator', device: { avdName: 'Pixel_6_API_33' } },
-  },
-};
-```
-
-### Detox E2E Tests
-
-```typescript
-describe('Login Flow', () => {
-  beforeAll(async () => {
-    await device.launchApp({ newInstance: true });
-  });
-
-  beforeEach(async () => {
-    await device.reloadReactNative();
-  });
-
-  it('logs in with valid credentials', async () => {
-    await element(by.id('email-input')).typeText('user@example.com');
-    await element(by.id('password-input')).typeText('password123');
-    await element(by.id('login-button')).tap();
-
-    await waitFor(element(by.id('dashboard-screen')))
-      .toBeVisible()
-      .withTimeout(5000);
-  });
-
-  it('shows error for invalid credentials', async () => {
-    await element(by.id('email-input')).typeText('wrong@example.com');
-    await element(by.id('password-input')).typeText('wrong');
-    await element(by.id('login-button')).tap();
-
-    await expect(element(by.text('Invalid credentials'))).toBeVisible();
-  });
-});
-```
-
-### Snapshot Testing for Components
-
-```typescript
-import { render } from '@testing-library/react-native';
-import { Button } from './Button';
-
-describe('Button snapshots', () => {
-  it('renders primary variant', () => {
-    const tree = render(<Button variant="primary" title="Submit" />);
-    expect(tree.toJSON()).toMatchSnapshot();
-  });
-
-  it('renders disabled state', () => {
-    const tree = render(<Button variant="primary" title="Submit" disabled />);
-    expect(tree.toJSON()).toMatchSnapshot();
-  });
-});
-```
-
-## Anti-Patterns
-
-1. **Not mocking native modules** — Unmocked native modules crash Jest. Set up
-   comprehensive mocks in jest/setup.ts for all native dependencies.
-
-2. **Testing styles directly** — Asserting on style objects is brittle. Test visual
-   outcomes with snapshots or accessibility labels instead.
-
-3. **Ignoring platform differences** — Platform.select branches need testing on
-   both platforms. Use parameterized tests with platform mocks.
-
-4. **Detox without synchronization** — Not waiting for animations or network calls
-   to complete before assertions. Use waitFor patterns.
-
-5. **Over-relying on snapshots** — Large component tree snapshots are unreviewed noise.
-   Use targeted snapshots for small, stable components only.
-
-## Integration Points
-
-- **Tools**: Jest, RNTL, Detox, Metro bundler
-- **Workflows**: `mobile-testing` (test plan), `test-framework` (initial setup)
-- **Related fragments**: `jest-vitest-patterns` (shared Jest patterns)

package/_gaia/testing/knowledge/mobile-testing/responsive-testing.md

@@ -1,177 +0,0 @@
----
-name: responsive-testing
-tier: mobile-testing
-version: '1.0'
----
-
-# Responsive Testing
-
-## Principle
-
-Responsive testing validates that applications adapt correctly across viewport sizes,
-orientations, and input methods. It bridges the gap between mobile and desktop testing
-by ensuring CSS breakpoints, touch interactions, and dynamic layouts work as designed.
-
-## Rationale
-
-Users access applications on devices ranging from 320px to 2560px wide. Responsive
-design failures — overlapping elements, hidden content, broken navigation — are among
-the most common UI bugs. Automated viewport testing catches layout regressions that
-manual testing misses.
-
-## Pattern Examples
-
-### Viewport Testing Matrix
-
-```typescript
-const viewports = [
-  { name: 'mobile-small', width: 320, height: 568 },   // iPhone SE
-  { name: 'mobile', width: 375, height: 812 },          // iPhone 13
-  { name: 'mobile-large', width: 428, height: 926 },    // iPhone 14 Pro Max
-  { name: 'tablet-portrait', width: 768, height: 1024 },// iPad
-  { name: 'tablet-landscape', width: 1024, height: 768 },
-  { name: 'laptop', width: 1366, height: 768 },
-  { name: 'desktop', width: 1920, height: 1080 },
-];
-
-for (const vp of viewports) {
-  test(`renders correctly at ${vp.name} (${vp.width}x${vp.height})`, async ({ page }) => {
-    await page.setViewportSize({ width: vp.width, height: vp.height });
-    await page.goto('/dashboard');
-    await expect(page.locator('[data-testid="main-content"]')).toBeVisible();
-  });
-}
-```
-
-### CSS Breakpoint Coverage
-
-```typescript
-describe('Navigation', () => {
-  test('shows hamburger menu on mobile', async ({ page }) => {
-    await page.setViewportSize({ width: 375, height: 812 });
-    await page.goto('/');
-    await expect(page.locator('[data-testid="hamburger-menu"]')).toBeVisible();
-    await expect(page.locator('[data-testid="desktop-nav"]')).toBeHidden();
-  });
-
-  test('shows full nav on desktop', async ({ page }) => {
-    await page.setViewportSize({ width: 1920, height: 1080 });
-    await page.goto('/');
-    await expect(page.locator('[data-testid="desktop-nav"]')).toBeVisible();
-    await expect(page.locator('[data-testid="hamburger-menu"]')).toBeHidden();
-  });
-
-  test('collapses sidebar on tablet', async ({ page }) => {
-    await page.setViewportSize({ width: 768, height: 1024 });
-    await page.goto('/dashboard');
-    await expect(page.locator('[data-testid="sidebar"]')).toHaveCSS('width', '64px');
-  });
-});
-```
-
-### Visual Regression with Percy/Chromatic
-
-```typescript
-// Percy integration with Playwright
-import percySnapshot from '@percy/playwright';
-
-test('homepage visual regression', async ({ page }) => {
-  await page.goto('/');
-
-  // Capture at multiple widths
-  await percySnapshot(page, 'Homepage - Mobile', { widths: [375] });
-  await percySnapshot(page, 'Homepage - Tablet', { widths: [768] });
-  await percySnapshot(page, 'Homepage - Desktop', { widths: [1920] });
-});
-
-// Chromatic integration (Storybook)
-// stories/Button.stories.tsx
-export default {
-  title: 'Components/Button',
-  component: Button,
-  parameters: {
-    chromatic: {
-      viewports: [320, 768, 1200],
-    },
-  },
-};
-```
-
-### Touch vs Click Interaction Testing
-
-```typescript
-describe('Touch interactions', () => {
-  test('swipe to delete on mobile', async ({ page }) => {
-    await page.setViewportSize({ width: 375, height: 812 });
-    await page.goto('/list');
-
-    const item = page.locator('[data-testid="list-item-1"]');
-    const box = await item.boundingBox();
-
-    await page.mouse.move(box!.x + box!.width - 10, box!.y + box!.height / 2);
-    await page.mouse.down();
-    await page.mouse.move(box!.x + 10, box!.y + box!.height / 2, { steps: 10 });
-    await page.mouse.up();
-
-    await expect(page.locator('[data-testid="delete-action"]')).toBeVisible();
-  });
-
-  test('hover tooltip on desktop', async ({ page }) => {
-    await page.setViewportSize({ width: 1920, height: 1080 });
-    await page.goto('/');
-
-    await page.hover('[data-testid="info-icon"]');
-    await expect(page.locator('[role="tooltip"]')).toBeVisible();
-  });
-
-  test('long press context menu on mobile', async ({ page }) => {
-    await page.setViewportSize({ width: 375, height: 812 });
-    await page.goto('/list');
-
-    const item = page.locator('[data-testid="list-item-1"]');
-    await item.click({ delay: 1000 }); // simulate long press
-
-    await expect(page.locator('[data-testid="context-menu"]')).toBeVisible();
-  });
-});
-```
-
-### Orientation Testing
-
-```typescript
-describe('Orientation changes', () => {
-  test('landscape mode adjusts layout', async ({ page }) => {
-    // Portrait
-    await page.setViewportSize({ width: 375, height: 812 });
-    await page.goto('/video-player');
-    await expect(page.locator('[data-testid="controls"]')).toBeVisible();
-
-    // Landscape
-    await page.setViewportSize({ width: 812, height: 375 });
-    await expect(page.locator('[data-testid="fullscreen-controls"]')).toBeVisible();
-  });
-});
-```
-
-## Anti-Patterns
-
-1. **Testing only desktop** — Most traffic is mobile. Include at least 320px, 375px,
-   and 768px viewports in every visual regression suite.
-
-2. **Hardcoded pixel assertions** — Asserting `element.width === 375` is fragile.
-   Test visibility, layout behavior, and CSS properties instead.
-
-3. **Ignoring touch targets** — Buttons under 44x44px fail mobile usability. Validate
-   minimum touch target sizes in responsive tests.
-
-4. **Single breakpoint testing** — Testing only at exact breakpoints misses issues
-   at in-between sizes. Include non-standard widths like 360px, 414px, 834px.
-
-5. **Skipping orientation** — Many layouts break in landscape. Test both orientations
-   for tablet and mobile viewports.
-
-## Integration Points
-
-- **Tools**: Playwright, Percy, Chromatic, Storybook
-- **Workflows**: `mobile-testing` (test plan), `test-automation` (coverage expansion)
-- **Related fragments**: `visual-testing` (screenshot comparison), `selector-resilience` (locators)