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/30-record-gift.spec.ts

@@ -1,3 +1,83 @@
+/**
+ * @file Gift Recording Test Suite
+ * @description Tests TimeSafari's core gift recording functionality, ensuring proper creation,
+ * validation, and verification of gift records
+ * 
+ * This test verifies:
+ * 1. Gift Creation
+ *    - Random gift title generation
+ *    - Random non-zero amount assignment
+ *    - Proper recording and signing
+ * 
+ * 2. Gift Verification
+ *    - Gift appears in home view
+ *    - Details match input data
+ *    - Verifiable claim details accessible
+ * 
+ * 3. Public Verification
+ *    - Gift viewable on public server
+ *    - Claim details properly exposed
+ * 
+ * Test Flow:
+ * 1. Data Generation
+ *    - Generate random 4-char string for unique gift ID
+ *    - Generate random amount (1-99)
+ *    - Combine with standard "Gift" prefix
+ * 
+ * 2. Gift Recording
+ *    - Import User 00 (test account)
+ *    - Navigate to home
+ *    - Close onboarding dialog
+ *    - Select recipient
+ *    - Fill gift details
+ *    - Sign and submit
+ * 
+ * 3. Verification
+ *    - Check success notification
+ *    - Refresh home view
+ *    - Locate gift in list
+ *    - Verify gift details
+ *    - Check public server view
+ * 
+ * Test Data:
+ * - Gift Title: "Gift [4-char-random]"
+ * - Amount: Random 1-99
+ * - Recipient: "Unnamed/Unknown"
+ * 
+ * Key Selectors:
+ * - Gift title: '[data-testid="giftTitle"]'
+ * - Amount input: 'input[type="number"]'
+ * - Submit button: 'button[name="Sign & Send"]'
+ * - Success alert: 'div[role="alert"]'
+ * - Details section: 'h2[name="Details"]'
+ * 
+ * Alert Handling:
+ * - Closes onboarding dialog
+ * - Verifies success message
+ * - Dismisses info alerts
+ * 
+ * State Requirements:
+ * - Clean database state
+ * - User 00 imported
+ * - Available API rate limits
+ * 
+ * Related Files:
+ * - Gift recording view: src/views/RecordGiftView.vue
+ * - JWT creation: sw_scripts/safari-notifications.js
+ * - Endorser API: src/libs/endorserServer.ts
+ * 
+ * @see Documentation in usage-guide.md for gift recording workflows
+ * @requires @playwright/test
+ * @requires ./testUtils - For user management utilities
+ * 
+ * @example Basic gift recording
+ * ```typescript
+ * await page.getByPlaceholder('What was given').fill('Gift abc123');
+ * await page.getByRole('spinbutton').fill('42');
+ * await page.getByRole('button', { name: 'Sign & Send' }).click();
+ * await expect(page.getByText('That gift was recorded.')).toBeVisible();
+ * ```
+ */
 import { test, expect } from '@playwright/test';
 import { importUser } from './testUtils';