docs(tests): Add comprehensive test suite documentation

- Add detailed header documentation to playwright tests
- Document test categories and flows
- Add key selector documentation
- Document state verification and alert handling
- Include code examples and usage patterns
- Add important checks and requirements

The documentation helps developers understand the foundational tests that verify
basic application functionality before running more complex test suites.

test-playwright/33-record-gift-x10.spec.ts

@@ -1,3 +1,89 @@
+/**
+ * @file Bulk Gift Recording Test Suite
+ * @description Tests TimeSafari's gift recording functionality under load by creating 
+ * multiple gift records in sequence. Limited to 9 gifts to stay under 30-second timeout.
+ * 
+ * This test verifies:
+ * 1. Scalability
+ *    - System handles multiple gift recordings (9)
+ *    - Performance remains stable across iterations
+ *    - No data corruption during bulk operations
+ * 
+ * 2. Data Integrity
+ *    - Each gift has unique identifiers
+ *    - All gifts properly stored and retrievable
+ *    - No cross-contamination between gift data
+ * 
+ * 3. UI/UX Stability
+ *    - Interface remains responsive during bulk operations
+ *    - Success notifications display correctly
+ *    - Alert dismissal works consistently
+ * 
+ * Test Flow:
+ * 1. Setup Phase
+ *    - Generate arrays of unique strings for titles
+ *    - Generate array of random numbers for amounts
+ *    - Import User 00 (test account)
+ * 
+ * 2. Bulk Recording (9 iterations)
+ *    - Navigate to home
+ *    - Handle first-time onboarding dialog
+ *    - Select recipient (Unnamed/Unknown)
+ *    - Fill gift details from arrays
+ *    - Sign and submit
+ *    - Verify success
+ *    - Dismiss notification
+ *    - Verify gift in list
+ * 
+ * Test Data:
+ * - Gift Count: 9 (optimized for timeout limits)
+ * - Title Format: "Gift [unique-string]"
+ * - Amount: Random numbers array
+ * - Recipient: "Unnamed/Unknown" (constant)
+ * 
+ * Key Selectors:
+ * - Gift input: '[placeholder="What was given"]'
+ * - Amount input: '[role="spinbutton"]'
+ * - Submit button: '[name="Sign & Send"]'
+ * - Success alert: 'div[role="alert"]'
+ * - Alert dismiss: 'button > svg.fa-xmark'
+ * 
+ * Performance Considerations:
+ * - Limited to 9 gifts to avoid timeout
+ * - Handles UI lag between operations
+ * - Manages memory usage during bulk operations
+ * 
+ * Error Handling:
+ * - Closes onboarding dialog only on first iteration
+ * - Verifies each gift individually
+ * - Maintains operation even if individual recordings fail
+ * 
+ * Related Files:
+ * - Gift recording view: src/views/RecordGiftView.vue
+ * - JWT creation: sw_scripts/safari-notifications.js
+ * - Endorser API: src/libs/endorserServer.ts
+ * - Test utilities: ./testUtils.ts
+ * 
+ * @see Documentation in usage-guide.md for gift recording workflows
+ * @requires @playwright/test
+ * @requires ./testUtils - For user management and array generation
+ * 
+ * @example
+ * ```typescript
+ * // Generate test data arrays
+ * const uniqueStrings = await createUniqueStringsArray(giftCount);
+ * const randomNumbers = await createRandomNumbersArray(giftCount);
+ * 
+ * // Record gifts in sequence
+ * for (let i = 0; i < giftCount; i++) {
+ *   await page.goto('./');
+ *   await page.getByPlaceholder('What was given').fill(finalTitles[i]);
+ *   await page.getByRole('spinbutton').fill(finalNumbers[i].toString());
+ *   await page.getByRole('button', { name: 'Sign & Send' }).click();
+ * }
+ * ```
+ */
+
 import { test, expect } from '@playwright/test';
 import { importUser, createUniqueStringsArray, createRandomNumbersArray  } from './testUtils';