@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/mobile-app/mobile-app-testing.md

@@ -0,0 +1,400 @@
+---
+name: mobile-app-testing
+description: Unit tests, UI tests (XCTest/Espresso/Detox), snapshot tests, accessibility testing, and test architecture for iOS and Android
+topics: [mobile-app, testing, xctest, espresso, detox, snapshot-testing, accessibility-testing, unit-tests]
+---
+
+Mobile testing requires a multi-layer strategy: unit tests for business logic, integration tests for repository and network layers, UI tests for critical user flows, and snapshot tests for visual regression. The test pyramid applies — fast unit tests outnumber slow UI tests. Mobile UI tests are inherently fragile (timing, simulator state, animations) — structure them to minimize flakiness and run only the highest-value flows in CI.
+
+## Summary
+
+iOS testing uses XCTest for unit and UI tests, with third-party additions (Quick/Nimble for BDD, snapshot-testing for visual regression). Android uses JUnit4/5 + Mockito/MockK for unit tests, Espresso for UI tests (in-process), and optional Detox for cross-platform end-to-end testing. Snapshot tests catch unintended UI changes automatically. Test architecture follows the same clean separation as production code — inject fakes, not mocks, for stable tests. Run unit tests on every commit; UI tests on PR merge.
+
+## Deep Guidance
+
+### iOS Unit Testing (XCTest)
+
+**Test file structure**
+```swift
+import XCTest
+@testable import MyApp
+
+final class UserProfileViewModelTests: XCTestCase {
+    var sut: UserProfileViewModel!   // System Under Test
+    var mockRepository: MockUserRepository!
+
+    override func setUp() {
+        super.setUp()
+        mockRepository = MockUserRepository()
+        sut = UserProfileViewModel(repository: mockRepository)
+    }
+
+    override func tearDown() {
+        sut = nil
+        mockRepository = nil
+        super.tearDown()
+    }
+
+    func test_loadUser_success_setsUserOnState() async throws {
+        // Arrange
+        let expectedUser = User(id: "1", name: "Jane", email: "jane@example.com")
+        mockRepository.stubbedUser = expectedUser
+
+        // Act
+        await sut.loadUser(id: "1")
+
+        // Assert
+        XCTAssertEqual(sut.user, expectedUser)
+        XCTAssertFalse(sut.isLoading)
+        XCTAssertNil(sut.error)
+    }
+
+    func test_loadUser_failure_setsErrorOnState() async {
+        // Arrange
+        mockRepository.stubbedError = NetworkError.serverError(500)
+
+        // Act
+        await sut.loadUser(id: "1")
+
+        // Assert
+        XCTAssertNil(sut.user)
+        XCTAssertNotNil(sut.error)
+    }
+}
+```
+
+**Protocol-based fakes over Mocks**
+```swift
+protocol UserRepository {
+    func fetchUser(id: String) async throws -> User
+    func updateUser(_ user: User) async throws
+}
+
+// Fake — implements the real behavior with in-memory data
+final class FakeUserRepository: UserRepository {
+    var stubbedUser: User?
+    var stubbedError: Error?
+    var updatedUsers: [User] = []
+
+    func fetchUser(id: String) async throws -> User {
+        if let error = stubbedError { throw error }
+        return stubbedUser ?? User(id: id, name: "Test User", email: "test@example.com")
+    }
+
+    func updateUser(_ user: User) async throws {
+        if let error = stubbedError { throw error }
+        updatedUsers.append(user)
+    }
+}
+```
+
+Fakes are preferable to generated mocks (Cuckoo, Mockingbird) because they compile without code generation, work in Swift Previews, and test realistic behavior rather than exact call sequences.
+
+**Testing async code**
+```swift
+// Test async throws with async test methods (Swift concurrency)
+func test_loadUser_callsRepository() async throws {
+    let result = try await sut.loadUser(id: "1")
+    XCTAssertEqual(result.id, "1")
+}
+
+// Test Combine publishers
+func test_isLoading_trueWhileLoading() {
+    var loadingStates: [Bool] = []
+    let expectation = expectation(description: "Loading state changes")
+    expectation.expectedFulfillmentCount = 3  // false → true → false
+
+    let cancellable = sut.$isLoading.sink { loadingStates.append($0) }
+
+    Task { await sut.loadUser(id: "1") }
+
+    wait(for: [expectation], timeout: 2.0)
+    XCTAssertEqual(loadingStates, [false, true, false])
+}
+
+// Performance tests
+func test_fetchAllUsers_performance() throws {
+    measure {
+        let _ = try! mockRepository.fetchAllUsers()
+    }
+}
+```
+
+### Android Unit Testing (JUnit + MockK)
+
+**ViewModel unit test**
+```kotlin
+@OptIn(ExperimentalCoroutinesApi::class)
+class UserProfileViewModelTest {
+
+    @get:Rule val mainDispatcherRule = MainDispatcherRule()  // replaces Main dispatcher with test dispatcher
+
+    private val userRepository = mockk<UserRepository>()
+    private lateinit var viewModel: UserProfileViewModel
+
+    @BeforeEach
+    fun setUp() {
+        viewModel = UserProfileViewModel(userRepository)
+    }
+
+    @Test
+    fun `loadUser success sets user in state`() = runTest {
+        // Arrange
+        val expectedUser = User(id = "1", name = "Jane", email = "jane@example.com")
+        coEvery { userRepository.fetchUser("1") } returns Result.success(expectedUser)
+
+        // Act
+        viewModel.loadUser("1")
+        advanceUntilIdle()
+
+        // Assert
+        val state = viewModel.uiState.value
+        assertThat(state.user).isEqualTo(expectedUser)
+        assertThat(state.isLoading).isFalse()
+        assertThat(state.error).isNull()
+    }
+
+    @Test
+    fun `loadUser failure sets error in state`() = runTest {
+        coEvery { userRepository.fetchUser(any()) } returns Result.failure(IOException("Network error"))
+
+        viewModel.loadUser("1")
+        advanceUntilIdle()
+
+        assertThat(viewModel.uiState.value.error).isNotNull()
+    }
+}
+```
+
+**MainDispatcherRule (required for ViewModel tests)**
+```kotlin
+class MainDispatcherRule(
+    private val dispatcher: TestCoroutineDispatcher = TestCoroutineDispatcher()
+) : TestWatcher() {
+    override fun starting(description: Description) {
+        Dispatchers.setMain(dispatcher)
+    }
+    override fun finished(description: Description) {
+        Dispatchers.resetMain()
+        dispatcher.cleanupTestCoroutines()
+    }
+}
+```
+
+**Repository integration test (with in-memory Room)**
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class UserRepositoryTest {
+    private lateinit var database: AppDatabase
+    private lateinit var userDao: UserDao
+
+    @Before
+    fun setUp() {
+        database = Room.inMemoryDatabaseBuilder(
+            ApplicationProvider.getApplicationContext(),
+            AppDatabase::class.java
+        ).allowMainThreadQueries().build()
+        userDao = database.userDao()
+    }
+
+    @After
+    fun tearDown() {
+        database.close()
+    }
+
+    @Test
+    fun insertAndRetrieveUser() = runTest {
+        val user = UserEntity(id = "1", name = "Jane", email = "jane@example.com", updatedAt = 0L)
+        userDao.upsert(user)
+        val retrieved = userDao.observeUsers().first()
+        assertThat(retrieved).contains(user)
+    }
+}
+```
+
+### UI Testing
+
+**iOS XCUITest**
+```swift
+final class LoginUITests: XCTestCase {
+    var app: XCUIApplication!
+
+    override func setUpWithError() throws {
+        continueAfterFailure = false
+        app = XCUIApplication()
+        app.launchArguments = ["--uitesting", "--reset-state"]
+        app.launch()
+    }
+
+    func test_login_validCredentials_navigatesToHome() throws {
+        let emailField = app.textFields["login_email_field"]
+        XCTAssertTrue(emailField.waitForExistence(timeout: 5))
+        emailField.tap()
+        emailField.typeText("test@example.com")
+
+        let passwordField = app.secureTextFields["login_password_field"]
+        passwordField.tap()
+        passwordField.typeText("password123")
+
+        app.buttons["login_submit_button"].tap()
+
+        let homeTitle = app.staticTexts["home_screen_title"]
+        XCTAssertTrue(homeTitle.waitForExistence(timeout: 10))
+    }
+}
+```
+
+Accessibility identifiers:
+```swift
+// Set in SwiftUI
+Button("Submit") { submitAction() }
+    .accessibilityIdentifier("login_submit_button")
+
+// Set in UIKit
+loginButton.accessibilityIdentifier = "login_submit_button"
+```
+
+Use `accessibilityIdentifier` for test targeting — never use display text or position-based queries which break on localization or layout changes.
+
+**Android Espresso**
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class LoginInstrumentedTest {
+
+    @get:Rule val activityRule = ActivityScenarioRule(LoginActivity::class.java)
+
+    @Test
+    fun login_validCredentials_navigatesToHome() {
+        onView(withId(R.id.email_field))
+            .perform(typeText("test@example.com"), closeSoftKeyboard())
+        onView(withId(R.id.password_field))
+            .perform(typeText("password123"), closeSoftKeyboard())
+        onView(withId(R.id.submit_button)).perform(click())
+
+        onView(withId(R.id.home_screen_title))
+            .check(matches(isDisplayed()))
+    }
+}
+```
+
+**Compose UI testing**
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class UserProfileScreenTest {
+
+    @get:Rule val composeTestRule = createComposeRule()
+
+    @Test
+    fun userCard_displaysName() {
+        val user = User(id = "1", name = "Jane Smith", email = "jane@example.com")
+        composeTestRule.setContent {
+            MyAppTheme { UserCard(user = user) }
+        }
+
+        composeTestRule.onNodeWithText("Jane Smith").assertIsDisplayed()
+        composeTestRule.onNodeWithContentDescription("User avatar").assertExists()
+    }
+}
+```
+
+### Snapshot Testing
+
+**iOS: swift-snapshot-testing (Point-Free)**
+```swift
+import SnapshotTesting
+
+final class UserCardSnapshotTests: XCTestCase {
+    func test_userCard_defaultState() {
+        let view = UserCardView(user: .fixture)
+        assertSnapshot(of: view, as: .image(on: .iPhone13Pro))
+    }
+
+    func test_userCard_loadingState() {
+        let view = UserCardView(isLoading: true)
+        assertSnapshot(of: view, as: .image(on: .iPhone13Pro))
+    }
+
+    func test_userCard_darkMode() {
+        let view = UserCardView(user: .fixture)
+        assertSnapshot(of: view, as: .image(on: .iPhone13Pro, traits: .init(userInterfaceStyle: .dark)))
+    }
+}
+```
+
+Run snapshots in `record` mode once to generate reference images, then in normal mode to detect regressions. Commit reference images to git. Update references only for intentional UI changes.
+
+**Android: Paparazzi (Cashapp)**
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class UserCardSnapshotTest {
+    @get:Rule val paparazzi = Paparazzi(deviceConfig = DeviceConfig.PIXEL_6)
+
+    @Test
+    fun userCard_defaultState() {
+        paparazzi.snapshot {
+            MyAppTheme {
+                UserCard(user = previewUser)
+            }
+        }
+    }
+}
+```
+
+Paparazzi runs on the JVM without a device or emulator — fast, CI-friendly.
+
+### Accessibility Testing
+
+**iOS: Accessibility Inspector + XCTest**
+```swift
+func test_loginButton_hasAccessibilityLabel() {
+    let button = app.buttons["login_submit_button"]
+    XCTAssertTrue(button.exists)
+    XCTAssertFalse(button.label.isEmpty)  // has accessibility label
+}
+```
+
+Automated accessibility audit:
+```swift
+func test_homeScreen_passesAccessibilityAudit() throws {
+    // iOS 17+: built-in accessibility audit
+    try app.performAccessibilityAudit()
+}
+```
+
+`performAccessibilityAudit()` checks: missing labels, insufficient contrast, small touch targets, and other WCAG violations automatically.
+
+**Android: Accessibility Test Framework**
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class AccessibilityTest {
+    @get:Rule val rule = AccessibilityChecksRule()  // auto-runs checks on every view interaction
+
+    @Test
+    fun loginScreen_allElementsAccessible() {
+        onView(withId(R.id.submit_button)).perform(click())
+        // AccessibilityChecksRule automatically fails on accessibility issues
+    }
+}
+```
+
+Compose accessibility testing:
+```kotlin
+composeTestRule.onNodeWithText("Submit")
+    .assertHasClickAction()
+    .assertContentDescriptionEquals("Submit order")
+    .assertIsEnabled()
+```
+
+### CI Test Strategy
+
+**What runs when**
+- Every commit: unit tests (fast, < 60 seconds)
+- Every PR: unit tests + instrumented tests on emulator (< 10 minutes)
+- Every merge to main: full suite including UI tests and snapshot tests (< 30 minutes)
+- Nightly: device farm run across full device matrix
+
+**Handling flaky tests**
+- Retry mechanism in CI: rerun failed tests up to 2 times before marking as failed
+- iOS: `--retry-tests-on-failure` flag in `xcodebuild test`
+- Android: `android { testOptions { unitTests { isReturnDefaultValues = true } } }`
+- Track flaky tests in a flakiness registry — tests flagged as flaky do not block merges but get prioritized for fixing

package/content/knowledge/web-app/web-app-api-patterns.md

@@ -0,0 +1,224 @@
+---
+name: web-app-api-patterns
+description: REST API design for web clients, GraphQL client patterns, error handling strategies, request deduplication, auth injection, and CORS
+topics: [web-app, api, rest, graphql, cors, error-handling, auth]
+---
+
+The API layer is the seam between frontend and backend. Poor design here manifests as waterfall requests that serialize page loads, inconsistent error shapes that require fragile client-side guessing, auth token handling bugs that cause random 401 errors, and CORS misconfigurations that block legitimate requests. A well-designed API client is boring: it handles auth transparently, errors consistently, and requests efficiently — so product engineers can focus on features rather than network plumbing.
+
+## Summary
+
+### REST API Design for Web Clients
+
+REST conventions for web clients go beyond HTTP verb selection:
+
+**Resource naming:** `/users/{id}/posts` not `/getUserPosts`. Nouns, not verbs. Plural collections.
+
+**Consistent response envelope:** Every response should have a predictable shape. Either always return the resource directly (`200 OK` with the object) or always wrap it (`{ data: {...}, meta: {...} }`) — never mix.
+
+**Status codes must be semantically correct:**
+- `200 OK` — successful read
+- `201 Created` — successful create (include `Location` header with new resource URL)
+- `204 No Content` — successful delete or update with no response body
+- `400 Bad Request` — validation failure (include field-level errors)
+- `401 Unauthorized` — not authenticated
+- `403 Forbidden` — authenticated but not authorized
+- `404 Not Found` — resource does not exist
+- `409 Conflict` — state conflict (duplicate resource, version mismatch)
+- `422 Unprocessable Entity` — business rule violation
+- `429 Too Many Requests` — rate limited (include `Retry-After` header)
+
+**Error response shape (standardize on RFC 7807 Problem Details):**
+```json
+{
+  "type": "https://api.example.com/errors/validation",
+  "title": "Validation Failed",
+  "status": 400,
+  "detail": "2 fields failed validation",
+  "errors": [
+    { "field": "email", "message": "Invalid email format" },
+    { "field": "username", "message": "Username already taken" }
+  ]
+}
+```
+
+### GraphQL Client Patterns
+
+GraphQL shifts the API design from server-defined endpoints to client-defined data requirements:
+
+**Fragments for co-location:** Define data requirements alongside the component that uses the data. This prevents over-fetching and makes it obvious when a component's data requirements change.
+
+**Normalized caching:** Apollo Client and urql maintain a normalized cache where each entity is stored once (by `__typename + id`) and automatically updated across all queries that reference it. Mutations that return the updated entity automatically update all queries that include that entity.
+
+**Fragment colocation pattern:** Each component defines its own fragment; the parent query composes them. This is the Relay-inspired pattern that scales to large teams.
+
+### Error Handling: Toast vs Inline
+
+Two display patterns for API errors, each appropriate in different contexts:
+
+**Toast notifications:** Background mutations, non-blocking operations, and errors where the user's current context is unchanged. "Failed to save changes — try again." The user doesn't lose their work.
+
+**Inline errors:** Form submissions, operations where the error requires user action to resolve. Show the error adjacent to the field or action that caused it. A `400` validation error must show which fields failed.
+
+**Never show raw API errors to users.** Map error codes to human-readable messages on the client. Log the technical detail to your error tracker.
+
+### Request Deduplication
+
+Multiple components mounting simultaneously and each calling the same endpoint produces redundant parallel requests. Deduplication ensures the second identical in-flight request waits for the first's result rather than issuing a new request.
+
+React Query deduplicates automatically — all components with the same `queryKey` share one in-flight request. For custom fetch layers, implement deduplication with a request-in-flight map.
+
+## Deep Guidance
+
+### API Client with Auth Injection and Token Refresh
+
+```typescript
+// api-client.ts — Centralized API client with automatic token refresh
+import ky from 'ky';  // Or axios, or native fetch
+
+let isRefreshing = false;
+let refreshQueue: Array<(token: string) => void> = [];
+
+export const apiClient = ky.create({
+  prefixUrl: process.env.NEXT_PUBLIC_API_URL,
+  hooks: {
+    beforeRequest: [
+      async (request) => {
+        const token = getAccessToken();  // From memory, not localStorage
+        if (token) {
+          request.headers.set('Authorization', `Bearer ${token}`);
+        }
+      },
+    ],
+    afterResponse: [
+      async (request, options, response) => {
+        if (response.status !== 401) return response;
+
+        // Token expired — refresh and retry
+        if (isRefreshing) {
+          // Queue this request until refresh completes
+          return new Promise((resolve) => {
+            refreshQueue.push((newToken) => {
+              request.headers.set('Authorization', `Bearer ${newToken}`);
+              resolve(ky(request));
+            });
+          });
+        }
+
+        isRefreshing = true;
+        try {
+          const newToken = await refreshAccessToken();
+          setAccessToken(newToken);
+
+          // Replay all queued requests with new token
+          refreshQueue.forEach(cb => cb(newToken));
+          refreshQueue = [];
+
+          // Retry the original request
+          request.headers.set('Authorization', `Bearer ${newToken}`);
+          return ky(request);
+        } catch (refreshError) {
+          // Refresh failed — redirect to login
+          clearSession();
+          window.location.href = '/login';
+          throw refreshError;
+        } finally {
+          isRefreshing = false;
+        }
+      },
+    ],
+  },
+});
+```
+
+The token refresh queue pattern prevents multiple simultaneous 401s from triggering multiple refresh requests. Only the first request initiates the refresh; subsequent requests queue and replay once the token is available.
+
+### CORS Configuration
+
+CORS is a browser-enforced security mechanism, not an API security mechanism. Servers must explicitly allow cross-origin requests from trusted origins.
+
+```typescript
+// Express CORS configuration
+import cors from 'cors';
+
+const allowedOrigins = [
+  'https://app.example.com',
+  'https://www.example.com',
+  // Development origins — only in non-production
+  ...(process.env.NODE_ENV !== 'production' ? ['http://localhost:3000'] : []),
+];
+
+app.use(cors({
+  origin: (origin, callback) => {
+    // Allow requests with no origin (server-to-server, curl)
+    if (!origin) return callback(null, true);
+    if (allowedOrigins.includes(origin)) return callback(null, true);
+    callback(new Error(`Origin ${origin} not allowed by CORS policy`));
+  },
+  credentials: true,      // Required when client sends cookies
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
+  exposedHeaders: ['X-Request-ID', 'X-Rate-Limit-Remaining'],
+  maxAge: 86400,          // Cache preflight for 24 hours (reduces OPTIONS requests)
+}));
+```
+
+**CORS mistakes to avoid:**
+- `origin: '*'` with `credentials: true` is invalid and rejected by browsers
+- Wildcard subdomain matching (`*.example.com`) requires explicit pattern matching, not a string
+- Missing `maxAge` causes an OPTIONS preflight on every non-simple cross-origin request
+
+### GraphQL Fragment Colocation
+
+```typescript
+// UserCard.tsx — Component defines its own data requirements
+const USER_CARD_FRAGMENT = gql`
+  fragment UserCardFields on User {
+    id
+    displayName
+    avatarUrl
+    followerCount
+  }
+`;
+
+function UserCard({ user }: { user: UserCardFields }) {
+  return (/* render using user.displayName, user.avatarUrl, etc. */);
+}
+
+UserCard.fragments = { user: USER_CARD_FRAGMENT };
+
+// ProfilePage.tsx — Composes fragments, doesn't know what UserCard needs
+const PROFILE_PAGE_QUERY = gql`
+  query ProfilePage($userId: ID!) {
+    user(id: $userId) {
+      ...UserCardFields
+      email        # Only ProfilePage needs this
+      createdAt
+    }
+  }
+  ${UserCard.fragments.user}
+`;
+```
+
+When `UserCard` needs a new field, the change is isolated to the fragment and its parent query is automatically updated. No need to modify multiple components or add fields "just in case."
+
+### API Error Handling Pattern
+
+```typescript
+// Typed error handling — map API errors to user-facing messages
+const API_ERROR_MESSAGES: Record<string, string> = {
+  'validation/email-taken': 'That email address is already registered.',
+  'auth/session-expired': 'Your session has expired. Please sign in again.',
+  'rate-limit/exceeded': 'Too many attempts. Please wait a moment and try again.',
+};
+
+function getErrorMessage(error: ApiError): string {
+  if (error.type && API_ERROR_MESSAGES[error.type]) {
+    return API_ERROR_MESSAGES[error.type];
+  }
+  // Safe fallback — never expose raw server errors
+  return 'Something went wrong. Please try again.';
+}
+```
+
+Maintain error message strings in one place. Never construct user-facing messages from raw `error.message` strings returned by the server.