gaia-framework 1.57.0 → 1.57.2

package/_gaia/testing/knowledge/specialized/visual-testing.md

@@ -1,129 +0,0 @@
----
-name: visual-testing
-tier: specialized
-version: '1.0'
----
-
-# Visual Testing
-
-## Principle
-
-Visual regression testing catches unintended UI changes by comparing screenshots against
-approved baselines. Test at the component level for speed and precision, at the page
-level for critical journeys. Configure thresholds carefully -- too strict causes noise,
-too loose misses real regressions.
-
-## Rationale
-
-CSS changes, font loading failures, layout shifts, and design system updates can break
-visual appearance without triggering any functional test failure. Visual tests fill this
-gap by asserting on what users actually see, not just what the DOM contains. They are
-the only reliable way to catch visual regressions across browsers and viewports.
-
-## Pattern Examples
-
-### Component-Level Visual Tests
-
-```typescript
-// tests/visual/button.visual.spec.ts
-import { test, expect } from '@playwright/test';
-
-test.describe('Button visual regression', () => {
-  for (const variant of ['primary', 'secondary', 'danger']) {
-    test(`${variant} button matches baseline`, async ({ page }) => {
-      await page.goto(`/storybook/button--${variant}`);
-      await expect(page.getByTestId('button')).toHaveScreenshot(
-        `button-${variant}.png`,
-        { maxDiffPixelRatio: 0.01 }
-      );
-    });
-  }
-});
-```
-
-### Page-Level Visual Tests
-
-```typescript
-test('dashboard layout matches baseline', async ({ page }) => {
-  // Mock dynamic content for determinism
-  await page.route('**/api/dashboard', (route) => {
-    route.fulfill({
-      body: JSON.stringify({
-        user: { name: 'Test User' },
-        stats: { orders: 42, revenue: 1234.56 },
-      }),
-    });
-  });
-
-  await page.goto('/dashboard');
-  await page.waitForLoadState('networkidle');
-
-  await expect(page).toHaveScreenshot('dashboard-full.png', {
-    fullPage: true,
-    maxDiffPixelRatio: 0.02,
-  });
-});
-```
-
-### Handling Dynamic Content
-
-```typescript
-test('profile page visual (with masked dynamic areas)', async ({ page }) => {
-  await page.goto('/profile');
-
-  // Mask elements with dynamic content (timestamps, avatars)
-  await expect(page).toHaveScreenshot('profile.png', {
-    mask: [
-      page.getByTestId('last-login-timestamp'),
-      page.getByTestId('user-avatar'),
-      page.getByTestId('notification-count'),
-    ],
-    maxDiffPixelRatio: 0.01,
-  });
-});
-```
-
-### Threshold Configuration
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  expect: {
-    toHaveScreenshot: {
-      maxDiffPixelRatio: 0.01,  // 1% pixel difference allowed
-      threshold: 0.2,           // Per-pixel color threshold (0-1)
-      animations: 'disabled',   // Disable CSS animations for stability
-    },
-  },
-  projects: [
-    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
-    { name: 'mobile', use: { ...devices['iPhone 14'] } },
-  ],
-});
-```
-
-## Anti-Patterns
-
-1. **Full-page screenshots with dynamic data** -- Timestamps, notification counts, and
-   random avatars cause every comparison to fail. Mask dynamic areas or mock the data.
-
-2. **Zero threshold** -- Requiring pixel-perfect matches causes failures from font
-   rendering differences across OS versions. Use `maxDiffPixelRatio: 0.01` minimum.
-
-3. **Only page-level tests** -- Full-page visual tests are slow and noisy. Prefer
-   component-level tests for design system elements. Reserve page-level for critical
-   layouts.
-
-4. **No cross-browser baselines** -- Chrome and Firefox render differently. Generate
-   separate baselines per browser/viewport combination.
-
-5. **Stale baselines** -- Baselines that are months old accumulate false positives. Update
-   baselines as part of the design change PR, not separately.
-
-## Integration Points
-
-- **Workflows**: `test-automation` (visual test generation), `test-review` (visual
-  regression audit)
-- **Related fragments**: `selector-resilience` (stable selectors for screenshot targets),
-  `deterministic-testing` (mocking dynamic content for stable screenshots),
-  `test-pyramid` (visual tests are E2E level)

package/_gaia/testing/knowledge/unit-testing/jest-vitest-patterns.md

@@ -1,193 +0,0 @@
----
-name: jest-vitest-patterns
-tier: unit-testing
-version: '1.0'
----
-
-# Jest & Vitest Patterns
-
-## Principle
-
-Fast feedback loops drive TDD adoption in JavaScript and TypeScript. Jest and Vitest
-provide near-identical APIs with different performance profiles — Vitest leverages
-Vite's transform pipeline for faster execution. Choose based on your bundler; the
-testing patterns remain the same.
-
-## Rationale
-
-JavaScript's module system and dynamic typing make mocking both powerful and dangerous.
-The describe/it/expect structure enables readable tests, but over-reliance on mocking
-internals creates brittle suites. Focus on testing behavior through public APIs and
-rendered output.
-
-## Pattern Examples
-
-### Basic Structure
-
-```typescript
-// src/utils/format-currency.test.ts
-import { formatCurrency } from './format-currency';
-
-describe('formatCurrency', () => {
-  it('formats USD with two decimal places', () => {
-    expect(formatCurrency(1234.5, 'USD')).toBe('$1,234.50');
-  });
-
-  it('handles zero', () => {
-    expect(formatCurrency(0, 'USD')).toBe('$0.00');
-  });
-
-  it('handles negative amounts', () => {
-    expect(formatCurrency(-50, 'USD')).toBe('-$50.00');
-  });
-});
-```
-
-### Parameterized Tests
-
-```typescript
-describe('validateEmail', () => {
-  it.each([
-    ['user@example.com', true],
-    ['user@sub.example.com', true],
-    ['invalid', false],
-    ['@example.com', false],
-    ['user@', false],
-  ])('validates %s as %s', (email, expected) => {
-    expect(validateEmail(email)).toBe(expected);
-  });
-});
-```
-
-### Module Mocking
-
-```typescript
-// Jest
-jest.mock('./api-client', () => ({
-  fetchUsers: jest.fn().mockResolvedValue([{ id: 1, name: 'Alice' }]),
-}));
-
-// Vitest
-vi.mock('./api-client', () => ({
-  fetchUsers: vi.fn().mockResolvedValue([{ id: 1, name: 'Alice' }]),
-}));
-
-// Manual mock — __mocks__/api-client.ts
-export const fetchUsers = jest.fn().mockResolvedValue([]);
-```
-
-### React Testing Library
-
-```typescript
-import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-import { LoginForm } from './LoginForm';
-
-describe('LoginForm', () => {
-  it('submits credentials', async () => {
-    const onSubmit = vi.fn();
-    render(<LoginForm onSubmit={onSubmit} />);
-
-    await userEvent.type(screen.getByLabelText('Email'), 'user@test.com');
-    await userEvent.type(screen.getByLabelText('Password'), 'secret123');
-    await userEvent.click(screen.getByRole('button', { name: 'Sign In' }));
-
-    expect(onSubmit).toHaveBeenCalledWith({
-      email: 'user@test.com',
-      password: 'secret123',
-    });
-  });
-
-  it('shows validation error for empty email', async () => {
-    render(<LoginForm onSubmit={vi.fn()} />);
-    await userEvent.click(screen.getByRole('button', { name: 'Sign In' }));
-    expect(screen.getByText('Email is required')).toBeInTheDocument();
-  });
-});
-```
-
-### Async Testing
-
-```typescript
-describe('UserService', () => {
-  it('fetches user by id', async () => {
-    const user = await userService.getById(1);
-    expect(user).toEqual(expect.objectContaining({ id: 1, name: 'Alice' }));
-  });
-
-  it('throws on not found', async () => {
-    await expect(userService.getById(999)).rejects.toThrow('User not found');
-  });
-});
-```
-
-### Snapshot Testing (Judicious Use)
-
-```typescript
-// Good — stable UI structure
-it('renders navigation menu', () => {
-  const { container } = render(<NavMenu items={menuItems} />);
-  expect(container.firstChild).toMatchSnapshot();
-});
-
-// Better — inline snapshot for small outputs
-it('formats address', () => {
-  expect(formatAddress(address)).toMatchInlineSnapshot(`
-    "123 Main St
-    Suite 100
-    New York, NY 10001"
-  `);
-});
-```
-
-### Setup and Teardown
-
-```typescript
-describe('DatabaseService', () => {
-  let db: TestDatabase;
-
-  beforeAll(async () => {
-    db = await TestDatabase.create();
-  });
-
-  afterAll(async () => {
-    await db.destroy();
-  });
-
-  beforeEach(async () => {
-    await db.seed(testData);
-  });
-
-  afterEach(async () => {
-    await db.truncate();
-  });
-
-  it('creates a record', async () => {
-    const record = await db.insert({ name: 'test' });
-    expect(record.id).toBeDefined();
-  });
-});
-```
-
-## Anti-Patterns
-
-1. **Implementation testing** — Testing that a function calls another internal function
-   rather than testing the observable output. Refactoring breaks these tests.
-
-2. **Snapshot overuse** — Large component snapshots that nobody reviews. Snapshots
-   should be small, targeted, and meaningful.
-
-3. **Testing framework internals** — Verifying React re-renders or state updates
-   instead of rendered output. Test what the user sees.
-
-4. **Mocking everything** — Mocking the module under test or its direct logic.
-   Only mock external dependencies and side effects.
-
-5. **Ignoring async cleanup** — Not awaiting cleanup in afterEach, causing test
-   pollution and flaky failures.
-
-## Integration Points
-
-- **Frameworks**: React (RTL), Next.js (next/jest), Express (supertest), Vue (vue-test-utils)
-- **Workflows**: `test-framework` (initial setup), `test-automation` (coverage expansion)
-- **Related fragments**: `fixture-architecture` (test helpers), `test-isolation` (isolation)

package/_gaia/testing/knowledge/unit-testing/junit5-patterns.md

@@ -1,200 +0,0 @@
----
-name: junit5-patterns
-tier: unit-testing
-version: '1.0'
----
-
-# JUnit 5 Patterns
-
-## Principle
-
-Strong typing enables compile-time test safety in Java. JUnit 5's extension model
-and parameterized test support provide flexible, type-safe test composition. Combined
-with Mockito and Spring test slices, it covers the full testing spectrum from unit
-to integration.
-
-## Rationale
-
-Java's verbose syntax makes test readability a priority. JUnit 5's annotations,
-@Nested classes for grouping, and @ParameterizedTest for data-driven tests reduce
-boilerplate while maintaining clarity. Spring Boot's test slices load only necessary
-context, keeping tests fast.
-
-## Pattern Examples
-
-### Basic Structure
-
-```java
-import org.junit.jupiter.api.*;
-import static org.assertj.core.api.Assertions.*;
-
-class PriceCalculatorTest {
-
-    private PriceCalculator calculator;
-
-    @BeforeEach
-    void setUp() {
-        calculator = new PriceCalculator();
-    }
-
-    @Test
-    @DisplayName("applies percentage discount correctly")
-    void appliesPercentageDiscount() {
-        BigDecimal result = calculator.applyDiscount(
-            new BigDecimal("100.00"),
-            Discount.percentage(20)
-        );
-        assertThat(result).isEqualByComparingTo("80.00");
-    }
-
-    @Test
-    @DisplayName("floors discount at zero")
-    void floorsDiscountAtZero() {
-        BigDecimal result = calculator.applyDiscount(
-            new BigDecimal("10.00"),
-            Discount.fixed(new BigDecimal("20.00"))
-        );
-        assertThat(result).isEqualByComparingTo("0.00");
-    }
-}
-```
-
-### Nested Groups and Parameterized Tests
-
-```java
-class UserServiceTest {
-    @Nested @DisplayName("when creating a user")
-    class CreateUser {
-        @Test void savesUserToDatabase() { /* ... */ }
-        @Test void sendsWelcomeEmail() { /* ... */ }
-        @Test void rejectsDuplicateEmail() { /* ... */ }
-    }
-    @Nested @DisplayName("when deleting a user")
-    class DeleteUser {
-        @Test void removesFromDatabase() { /* ... */ }
-        @Test void requiresAdminRole() { /* ... */ }
-    }
-}
-```
-
-```java
-@ParameterizedTest
-@CsvSource({
-    "hello, HELLO",
-    "Hello World, HELLO WORLD",
-    "'', ''",
-    "123abc, 123ABC"
-})
-void convertsToUpperCase(String input, String expected) {
-    assertThat(input.toUpperCase()).isEqualTo(expected);
-}
-
-@ParameterizedTest
-@MethodSource("provideInvalidEmails")
-void rejectsInvalidEmails(String email) {
-    assertThat(validator.isValid(email)).isFalse();
-}
-
-static Stream<String> provideInvalidEmails() {
-    return Stream.of("invalid", "@example.com", "user@", "", null);
-}
-```
-
-### Mockito Patterns
-
-```java
-@ExtendWith(MockitoExtension.class)
-class OrderServiceTest {
-    @Mock private OrderRepository orderRepository;
-    @Mock private PaymentGateway paymentGateway;
-    @InjectMocks private OrderService orderService;
-
-    @Test
-    void processesOrderSuccessfully() {
-        when(paymentGateway.charge(any())).thenReturn(PaymentResult.success());
-        Order order = orderService.placeOrder(new OrderRequest("item-1", 2));
-        assertThat(order.getStatus()).isEqualTo(OrderStatus.CONFIRMED);
-        verify(orderRepository).save(order);
-    }
-}
-```
-
-### Testcontainers for Integration
-
-```java
-@Testcontainers
-@SpringBootTest
-class UserRepositoryIntegrationTest {
-    @Container
-    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
-        .withDatabaseName("testdb");
-
-    @DynamicPropertySource
-    static void configureProperties(DynamicPropertyRegistry registry) {
-        registry.add("spring.datasource.url", postgres::getJdbcUrl);
-        registry.add("spring.datasource.username", postgres::getUsername);
-        registry.add("spring.datasource.password", postgres::getPassword);
-    }
-
-    @Autowired private UserRepository userRepository;
-
-    @Test
-    void savesAndRetrievesUser() {
-        userRepository.save(new User("Alice", "alice@example.com"));
-        Optional<User> found = userRepository.findByEmail("alice@example.com");
-        assertThat(found).isPresent();
-    }
-}
-```
-
-### Spring Boot Test Slices
-
-```java
-@WebMvcTest(UserController.class) // Only loads web layer
-class UserControllerTest {
-    @Autowired private MockMvc mockMvc;
-    @MockBean private UserService userService;
-
-    @Test
-    void returnsUserById() throws Exception {
-        when(userService.findById(1L)).thenReturn(new UserDto("Alice"));
-        mockMvc.perform(get("/api/users/1"))
-            .andExpect(status().isOk())
-            .andExpect(jsonPath("$.name").value("Alice"));
-    }
-}
-
-@DataJpaTest // Only loads JPA layer
-class OrderRepositoryTest {
-    @Autowired private TestEntityManager entityManager;
-    @Autowired private OrderRepository orderRepository;
-
-    @Test
-    void findsByStatus() {
-        entityManager.persist(new Order(OrderStatus.PENDING));
-        assertThat(orderRepository.findByStatus(OrderStatus.PENDING)).hasSize(1);
-    }
-}
-```
-
-## Anti-Patterns
-
-1. **Testing private methods** — If you need to test a private method, the class likely
-   violates SRP. Extract the logic into a separate class and test its public API.
-
-2. **Excessive mocking** — Mocking so many dependencies that the test validates nothing
-   real. If a test has 5+ mocks, consider an integration test instead.
-
-3. **Slow test suites** — Using @SpringBootTest for everything loads the full context.
-   Use test slices (@WebMvcTest, @DataJpaTest) for focused, fast tests.
-
-4. **Testing getters and setters** — Trivial code that cannot fail does not need tests.
-
-5. **Ignoring test naming** — @DisplayName should describe the expected behavior,
-   not the method name. "saves user" not "testSaveUser".
-
-## Integration Points
-
-- **Frameworks**: Spring Boot, JPA/Hibernate, Maven Surefire (unit), Failsafe (integration)
-- **Workflows**: `test-framework` (initial setup), `test-automation` (coverage expansion)
-- **Related fragments**: `fixture-architecture` (factory patterns), `test-isolation` (database isolation)

package/_gaia/testing/knowledge/unit-testing/pytest-patterns.md

@@ -1,185 +0,0 @@
----
-name: pytest-patterns
-tier: unit-testing
-version: '1.0'
----
-
-# Pytest Patterns
-
-## Principle
-
-Fixtures are the foundation of test architecture in Python. pytest's fixture system
-enables composable, scoped test dependencies that eliminate setup duplication while
-maintaining test isolation. Combine fixtures with parameterization for thorough
-coverage without test proliferation.
-
-## Rationale
-
-Python's dynamic nature makes test setup verbose without fixtures. pytest's dependency
-injection model lets tests declare what they need, not how to build it. This separation
-of concern keeps tests focused on assertions while fixtures handle the plumbing.
-
-## Pattern Examples
-
-### conftest.py Hierarchy
-
-```python
-# tests/conftest.py — shared across all tests
-import pytest
-from app import create_app
-from app.db import db as _db
-
-@pytest.fixture(scope="session")
-def app():
-    app = create_app(config="testing")
-    yield app
-
-@pytest.fixture(scope="session")
-def db(app):
-    with app.app_context():
-        _db.create_all()
-        yield _db
-        _db.drop_all()
-
-@pytest.fixture
-def session(db):
-    connection = db.engine.connect()
-    transaction = connection.begin()
-    session = db.create_scoped_session(bind=connection)
-    yield session
-    session.close()
-    transaction.rollback()
-    connection.close()
-```
-
-### Fixture Scoping
-
-```python
-# function — fresh per test (default, safest)
-@pytest.fixture
-def user():
-    return User(name="test", email="test@example.com")
-
-# class — shared within a test class
-@pytest.fixture(scope="class")
-def api_client(app):
-    return app.test_client()
-
-# module — shared within a file
-@pytest.fixture(scope="module")
-def expensive_resource():
-    return load_large_dataset()
-
-# session — shared across entire test run
-@pytest.fixture(scope="session")
-def database_engine():
-    return create_engine("sqlite:///:memory:")
-```
-
-### Parameterized Tests
-
-```python
-@pytest.mark.parametrize("input_val,expected", [
-    ("hello", "HELLO"),
-    ("Hello World", "HELLO WORLD"),
-    ("", ""),
-    ("123abc", "123ABC"),
-])
-def test_uppercase(input_val, expected):
-    assert input_val.upper() == expected
-
-@pytest.mark.parametrize("discount_type,amount,expected", [
-    ("percentage", 20, 80.0),
-    ("fixed", 15, 85.0),
-    ("percentage", 100, 0.0),
-    ("fixed", 200, 0.0),
-])
-def test_apply_discount(discount_type, amount, expected):
-    result = apply_discount(100, discount_type, amount)
-    assert result == expected
-```
-
-### Factory Fixtures
-
-```python
-@pytest.fixture
-def make_user(session):
-    def _make_user(name="test", email=None, role="user"):
-        email = email or f"{name}@example.com"
-        user = User(name=name, email=email, role=role)
-        session.add(user)
-        session.commit()
-        return user
-    return _make_user
-
-def test_admin_permissions(make_user):
-    admin = make_user(name="admin", role="admin")
-    assert admin.can("delete_users")
-
-def test_regular_user_restrictions(make_user):
-    user = make_user(name="regular", role="user")
-    assert not user.can("delete_users")
-```
-
-### Mocking with pytest-mock
-
-```python
-def test_send_notification(mocker):
-    mock_smtp = mocker.patch("app.notifications.smtplib.SMTP")
-    send_welcome_email("user@example.com")
-    mock_smtp.return_value.sendmail.assert_called_once()
-
-def test_external_api_call(mocker):
-    mocker.patch(
-        "app.services.requests.get",
-        return_value=mocker.Mock(status_code=200, json=lambda: {"data": "value"})
-    )
-    result = fetch_external_data()
-    assert result == {"data": "value"}
-```
-
-### Async Testing
-
-```python
-import pytest
-
-@pytest.mark.asyncio
-async def test_async_fetch(aiohttp_client):
-    client = await aiohttp_client(app)
-    resp = await client.get("/api/data")
-    assert resp.status == 200
-    data = await resp.json()
-    assert "items" in data
-
-@pytest.mark.asyncio
-async def test_concurrent_operations():
-    results = await asyncio.gather(
-        process_item("a"),
-        process_item("b"),
-        process_item("c"),
-    )
-    assert all(r.success for r in results)
-```
-
-## Anti-Patterns
-
-1. **Global state between tests** — Tests modifying module-level variables create
-   ordering dependencies. Use fixtures with function scope instead.
-
-2. **Test interdependence** — Test B relying on side effects from Test A. Each test
-   must set up its own state via fixtures.
-
-3. **Over-mocking** — Mocking the system under test rather than its dependencies.
-   Mock at boundaries, not at the core logic.
-
-4. **Broad fixture scope without cleanup** — Session-scoped fixtures that accumulate
-   state across tests. Always pair with proper teardown.
-
-5. **Fixture overuse** — Simple values (strings, numbers) passed as fixtures instead
-   of inline constants. Fixtures are for complex setup, not constants.
-
-## Integration Points
-
-- **Frameworks**: pytest-django (Django), pytest-flask (Flask), httpx/TestClient (FastAPI)
-- **Workflows**: `test-framework` (initial setup), `test-automation` (coverage expansion)
-- **Related fragments**: `fixture-architecture` (fixture design), `test-isolation` (isolation strategies)