@layers-app/editor 0.3.11 → 0.4.1-progress-bar.2

package/README.md

@@ -414,7 +414,7 @@ For uploading a file or audio, you might need the third parameter "data".
   <summary>
     📝 Additional options
   </summary>
-  
+
 ## Reset editor content
 
 ```
@@ -441,6 +441,220 @@ import {  CLEAR_EDITOR_COMMAND } from './EditorLexical';
 ```
 
 </details>
+
+<details>
+  <summary>
+    🧪 Testing
+  </summary>
+
+## Testing Overview
+
+This project includes comprehensive testing with both **unit tests** (Vitest) and **end-to-end tests** (Playwright). The testing setup ensures reliability across different browsers and environments.
+
+### Prerequisites
+
+Before running tests, make sure you have installed all dependencies:
+
+```bash
+npm install
+```
+
+## Unit Tests (Vitest)
+
+Unit tests are written with **Vitest** and **jsdom** for testing individual components and utilities.
+
+### Run Unit Tests
+
+```bash
+# Run all unit tests
+npm run test-unit
+
+# Run unit tests in watch mode (auto-rerun on changes)
+npm run test-unit-watch
+```
+
+### Unit Test Files Location
+- `__tests__/unit/` - Unit test files
+- Test files follow the pattern: `*.test.ts` or `*.test.tsx`
+
+## End-to-End Tests (Playwright)
+
+E2E tests use **Playwright** to test the complete application flow in real browsers.
+
+### Run E2E Tests
+
+```bash
+# Run all E2E tests (WebKit only for CI optimization)
+npm run test:e2e
+
+# Run E2E tests with UI mode (interactive)
+npm run test:e2e:ui
+
+# Run E2E tests in debug mode
+npm run test:e2e:debug
+
+# Run E2E tests in headed mode (visible browser)
+npm run test:e2e:headed
+```
+
+### E2E Test Files Location
+- `__tests__/e2e/` - End-to-end test files
+- `__tests__/regression/` - Regression test files
+- Test files follow the pattern: `*.spec.js`, `*.spec.mjs`, or `*.spec.ts`
+
+### Browser Support
+- **WebKit** (Safari) - Primary browser for CI/CD
+- **Chromium** and **Firefox** - Available for local testing
+
+## Test Server
+
+The test server automatically starts when running E2E tests:
+
+```bash
+# Manual test server start (if needed)
+npm run start-test-server
+```
+
+- **URL**: `http://localhost:3000`
+- **Mode**: Full editor mode with all features enabled
+- **Environment**: `VITE_LAYERS=true`
+
+## Test Configuration
+
+### Playwright Configuration
+- **Config file**: `playwright.config.js`
+- **Test directory**: `./__tests__/e2e/`
+- **Browser**: WebKit (optimized for CI)
+- **Base URL**: `http://localhost:3000`
+- **Timeout**: 90 seconds per test
+- **Retries**: 2 retries in CI, 0 locally
+
+### Vitest Configuration
+- **Config file**: `vitest.config.mts`
+- **Environment**: jsdom
+- **Setup file**: `vitest.setup.mts`
+- **Coverage**: V8 provider
+
+## CI/CD Testing
+
+Tests run automatically on:
+- **Push** to `main` or `dev` branches
+- **Pull requests** to `main` or `dev` branches
+- **Manual trigger** via GitHub Actions
+
+### GitHub Actions Workflow
+- **File**: `.github/workflows/tests.yml`
+- **Runner**: Ubuntu Latest
+- **Node.js**: Version 20
+- **Browser caching**: Playwright browsers cached for faster runs
+- **Artifacts**: Test reports and traces uploaded on completion
+
+## Test Examples
+
+### Basic E2E Test Structure
+
+```javascript
+// __tests__/e2e/example.spec.mjs
+import { test, expect } from '@playwright/test';
+import { focusEditor } from '../utils/index.mjs';
+
+test('Can type text in editor', async ({ page }) => {
+  await page.goto('/');
+  await focusEditor(page);
+
+  const editor = page.locator('[contenteditable="true"]').first();
+  await editor.type('Hello World');
+
+  await expect(editor).toContainText('Hello World');
+});
+```
+
+### Unit Test Structure
+
+```typescript
+// __tests__/unit/example.test.ts
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { Editor } from '../src/Editor';
+
+describe('Editor Component', () => {
+  it('renders without crashing', () => {
+    const { container } = render(<Editor />);
+    expect(container).toBeTruthy();
+  });
+});
+```
+
+## Debugging Tests
+
+### Debug E2E Tests
+
+```bash
+# Run with Playwright Inspector
+npm run test:e2e:debug
+
+# Run specific test file
+npx playwright test __tests__/e2e/TextEntry.spec.mjs --debug
+
+# Run with headed browser
+npm run test:e2e:headed
+```
+
+### View Test Reports
+
+```bash
+# Open HTML report (after running tests)
+npx playwright show-report
+
+# View test traces (for failed tests)
+npx playwright show-trace test-results/[test-name]/trace.zip
+```
+
+## Test Utilities
+
+Common test utilities are available in `__tests__/utils/index.mjs`:
+
+- `focusEditor(page)` - Focus the main editor
+- `selectAll(page)` - Select all text in editor
+- `moveLeft(page, count)` - Move cursor left
+- `selectCharacters(page, count)` - Select specific number of characters
+- `waitForSelector(page, selector)` - Wait for element to appear
+
+## Performance
+
+### Test Execution Times
+- **Unit Tests**: ~10-30 seconds
+- **E2E Tests (first run)**: ~3-4 minutes (includes browser installation)
+- **E2E Tests (cached)**: ~1-2 minutes (uses cached browsers)
+
+### Optimization Features
+- **Browser Caching**: Playwright browsers cached in CI
+- **Single Worker**: Prevents race conditions in CI
+- **WebKit Only**: Faster than multi-browser matrix
+- **Smart Retries**: Auto-retry flaky tests
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Port conflicts**: Ensure port 3000 is available
+2. **Browser installation**: Run `npx playwright install` if needed
+3. **Test timeouts**: Check if test server is running properly
+4. **Certificate errors**: Tests use HTTP to avoid HTTPS certificate issues
+
+### Reset Test Environment
+
+```bash
+# Clear Playwright cache
+npx playwright install --force
+
+# Reset node_modules
+rm -rf node_modules package-lock.json
+npm install
+```
+
+</details>
+
 <details>
   <summary>
     ⚙️ Properties