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/10-check-usage-limits.spec.ts

@@ -1,9 +1,67 @@
+/**
+ * End-to-End Contact Management Tests
+ * 
+ * Comprehensive test suite for Time Safari's contact management and gift recording features.
+ * Tests run sequentially to avoid state conflicts and API rate limits.
+ * 
+ * Test Flow:
+ * 1. Contact Creation & Verification
+ *    - Add contact using DID
+ *    - Verify contact appears in list
+ *    - Rename contact and verify change
+ *    - Check contact appears in "Record Something" section
+ * 
+ * 2. Gift Recording Flow
+ *    - Generate unique gift details
+ *    - Record gift to contact
+ *    - Verify gift confirmation
+ *    - Check gift appears in activity feed
+ * 
+ * 3. Contact Import/Export Tests
+ *    - Copy contact details to clipboard
+ *    - Delete existing contact
+ *    - Import contact from clipboard
+ *    - Verify imported contact details
+ * 
+ * Test Data Generation:
+ * - Gift titles: "Gift " + 16-char random string
+ * - Gift amounts: Random 1-99 value
+ * - Contact names: Predefined test values
+ * - DIDs: Uses test accounts (e.g., did:ethr:0x000...)
+ * 
+ * Key Selectors:
+ * - Contact list: 'li[data-testid="contactListItem"]'
+ * - Gift recording: '#sectionRecordSomethingGiven'
+ * - Contact name: '[data-testid="contactName"] input'
+ * - Alert dialogs: 'div[role="alert"]'
+ * 
+ * Timeouts & Retries:
+ * - Uses OS-specific timeouts (longer for Linux)
+ * - Implements retry logic for network operations
+ * - Waits for UI animations and state changes
+ * 
+ * Alert Handling:
+ * - Closes onboarding dialogs
+ * - Handles registration prompts
+ * - Verifies alert dismissal
+ * 
+ * State Requirements:
+ * - Clean database state
+ * - No existing contacts for test DIDs
+ * - Available API rate limits
+ * 
+ * @example Basic contact addition
+ * ```typescript
+ * await page.goto('./contacts');
+ * await page.getByPlaceholder('URL or DID, Name, Public Key')
+ *   .fill('did:ethr:0x000...., User Name');
+ * await page.locator('button > svg.fa-plus').click();
+ * ```
+ */
 import { test, expect } from '@playwright/test';
-import { importUser, isLinuxEnvironment, getOSSpecificTimeout } from './testUtils';
+import { importUser } from './testUtils';
 
 test('Check usage limits', async ({ page }) => {
-  const TIMEOUT = getOSSpecificTimeout();
-
   // Check without ID first
   await page.goto('./account');
   await expect(page.locator('div.bg-slate-100.rounded-md').filter({ hasText: 'Usage Limits' })).toBeHidden();
@@ -11,27 +69,20 @@ test('Check usage limits', async ({ page }) => {
   // Import user 01
   const did = await importUser(page, '01');
 
-  // Verify that "Usage Limits" section is visible with increased timeout
-  await expect(page.locator('#sectionUsageLimits')).toBeVisible({ timeout: TIMEOUT });
-  await expect(page.locator('#sectionUsageLimits')).toContainText('You have done', { timeout: TIMEOUT });
+  // Verify that "Usage Limits" section is visible
+  await expect(page.locator('#sectionUsageLimits')).toBeVisible();
+  await expect(page.locator('#sectionUsageLimits')).toContainText('You have done');
+  await expect(page.locator('#sectionUsageLimits')).toContainText('You have uploaded');
 
-  if (!isLinuxEnvironment()) {
-    await expect(page.locator('#sectionUsageLimits')).toContainText('You have uploaded');
-  }
-
-  // Add conditional checks for Linux environment
-  if (!isLinuxEnvironment()) {
-    await expect(page.getByText('Your image counter resets')).toBeVisible({ timeout: TIMEOUT });
-  }
-
-  // These checks should work on all environments
-  await expect(page.getByText('Your claims counter resets')).toBeVisible({ timeout: TIMEOUT });
-  await expect(page.getByText('Your registration counter resets')).toBeVisible({ timeout: TIMEOUT });
-  await expect(page.getByRole('button', { name: 'Recheck Limits' })).toBeVisible({ timeout: TIMEOUT });
+  await expect(page.getByText('Your claims counter resets')).toBeVisible();
+  await expect(page.getByText('Your registration counter resets')).toBeVisible();
+  await expect(page.getByText('Your image counter resets')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Recheck Limits' })).toBeVisible();
 
   // Set name
   await page.getByRole('button', { name: 'Set Your Name' }).click();
   const name = 'User ' + did.slice(11, 14);
   await page.getByPlaceholder('Name').fill(name);
   await page.getByRole('button', { name: 'Save', exact: true }).click();
+
 });