Skip to content

Commit 3078886

Browse files
jsoningramjsoningram
committed
Update README
1 parent 9312ae8 commit 3078886

2 files changed

Lines changed: 147 additions & 63 deletions

File tree

‎README.md‎

Lines changed: 113 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,17 @@ Events anonymously logged via pixels.js
3939
- **`app/page.tsx`** - Main page component managing widget lifecycle and event handlers
4040
- **`components/consent-form/`** - Privacy consent form shown before widget loads
4141
- **`components/footer/`** - Site footer with links and company information
42+
- **`components/burn-animation/`** - Fullscreen burn animation overlay displayed when clearing conversation data
43+
- `burn-overlay.tsx` - Overlay wrapper that fetches and displays Lottie animation
44+
- `burn-animation.tsx` - Lottie animation component wrapper
45+
- **`components/fire-button/`** - Button component for clearing conversation data (icon or button appearance)
46+
- **`components/confirm-dialog/`** - Modal confirmation dialog for clearing conversation data with keyboard navigation and focus management
47+
- **`components/chat-navigation/`** - Navigation links displayed below the chat widget (FAQs, Feedback)
48+
- **`components/main-heading/`** - Main page heading component with consistent branding
49+
- **`components/horizontal-rule/`** - Visual separator component for section divisions
50+
- **`components/new-tab-label/`** - Screen reader label for links that open in new tabs
51+
- **`components/button/`** - Reusable button component with customizable styling
52+
- **`components/page-load-pixel/`** - Component that fires page impression pixel on mount
4253

4354
### Zendesk Integration
4455

@@ -55,7 +66,12 @@ The application uses three main hooks for Zendesk integration (see [`src/hooks/R
5566
- **`utils/build-article-url.ts`** - Builds complete article URLs using the URL constructor
5667
- **`utils/update-article-links.ts`** - Updates article links in a document based on article ID mapping
5768
- **`utils/get-css-variable.ts`** - Reads CSS variable values from the document root
58-
- **`utils/get-slug-from-url.ts`** - Extracts and sanitizes the last path segment from a URL for use in pixel event tracking
69+
- **`utils/get-slug-from-url.ts`** - Extracts and sanitizes the last path segment from a URL for use in pixel event logging
70+
- **`utils/get-storage-with-expiry.ts`** - Retrieves boolean values from localStorage with date-based expiry (YYYY-MM-DD format)
71+
- **`utils/set-storage-with-expiry.ts`** - Stores boolean values in localStorage with date-based expiry (YYYY-MM-DD format)
72+
- **`utils/delete-storage-keys-by-suffix.ts`** - Deletes localStorage keys matching a suffix pattern
73+
- **`utils/is-browser.ts`** - Checks if code is running in a browser environment (SSR safety)
74+
- **`utils/cleanup-zendesk.ts`** - Cleans up all Zendesk DOM elements, scripts, and global objects when resetting the widget
5975

6076
### Logging
6177

@@ -120,6 +136,34 @@ npm run build
120136
npm start
121137
```
122138

139+
### Testing
140+
141+
The project uses Playwright for testing. See [`src/tests/README.md`](./src/tests/README.md) for comprehensive testing documentation.
142+
143+
```bash
144+
# Run all tests
145+
npm test
146+
147+
# Run with UI mode (interactive)
148+
npm run test:ui
149+
150+
# Run in headed mode (visible browser)
151+
npm run test:headed
152+
153+
# Run only integration tests
154+
npm test -- src/tests/integration/
155+
156+
# Run only unit tests
157+
npm test -- src/tests/unit/
158+
```
159+
160+
**Test Coverage:**
161+
162+
- ✅ 19 unit tests - Pure utility function tests (build-article-url, get-slug-from-url, get-storage-with-expiry)
163+
- ✅ 9 integration tests - Complete end-to-end user flow tests with Zendesk widget mocking
164+
165+
Tests run automatically in CI before deployment.
166+
123167
## Configuration
124168

125169
### Common Configuration
@@ -142,50 +186,74 @@ Zendesk configuration is in `src/config/zendesk.ts`:
142186

143187
```
144188
src/
145-
├── app/ # Next.js App Router pages
146-
│ ├── layout.tsx # Root layout with header, footer, theme provider
147-
│ └── page.tsx # Main page with Zendesk integration
148-
├── components/ # React components
149-
│ ├── button/ # Reusable button component
150-
│ ├── consent-form/ # Privacy consent form
151-
│ ├── footer/ # Site footer
152-
│ └── page-load-pixel/ # Page load event dispatcher
153-
├── config/ # Configuration constants
154-
│ ├── common.ts # Common site configuration
155-
│ ├── fonts.ts # Font configuration
156-
│ └── zendesk.ts # Zendesk widget configuration
157-
├── constants/ # Application constants
158-
│ ├── breakpoints.ts # Responsive breakpoint constants
159-
│ ├── footerLinks.ts # Footer link definitions
160-
│ ├── zendesk-selectors.ts # CSS selectors for Zendesk elements
161-
│ ├── zendesk-styles.ts # Custom CSS for Zendesk iframe
162-
│ └── zendesk-timing.ts # Timing constants for retries/delays
163-
├── hooks/ # React hooks
164-
│ ├── README.md # Documentation for Zendesk integration hooks
165-
│ ├── use-media-query.ts # Responsive design hook
166-
│ ├── use-zendesk-click-handlers.ts # Click event handlers
167-
│ ├── use-zendesk-iframe-styles.ts # Style injection
168-
│ └── use-zendesk-swap-article-links.ts # Article link swapping
169-
├── reducers/ # State reducers
170-
│ └── widget-reducer.ts # Widget lifecycle state reducer
171-
├── tests/ # Test files
172-
│ ├── fixtures/ # Test fixtures and mocks
173-
│ │ └── zendesk-mock.js # Zendesk widget mock for testing
174-
│ ├── integration/ # Integration tests
175-
│ │ └── complete-flow.test.ts # End-to-end user flow tests
176-
│ ├── unit/ # Unit tests
177-
│ │ ├── build-article-url.test.ts # URL building utility tests
178-
│ │ └── get-slug-from-url.test.ts # URL slug extraction tests
179-
│ └── README.md # Testing documentation
180-
├── types/ # TypeScript type definitions
181-
│ └── zendesk.d.ts # Extended Zendesk Web Widget types
182-
└── utils/ # Utility functions
183-
├── build-article-url.ts # URL building utility
184-
├── get-css-variable.ts # CSS variable reader
185-
├── get-slug-from-url.ts # URL slug extraction and sanitization
186-
├── update-article-links.ts # Link updating utility
187-
├── zendesk-iframe.ts # Iframe access utilities
188-
└── zendesk-observer.ts # MutationObserver setup utility
189+
├── app/ # Next.js App Router pages
190+
│ ├── layout.tsx # Root layout with header, footer, theme provider
191+
│ └── page.tsx # Main page with Zendesk integration
192+
├── components/ # React components
193+
│ ├── burn-animation/ # Burn animation overlay for clearing data
194+
│ ├── button/ # Reusable button component
195+
│ ├── chat-navigation/ # Navigation links below chat widget
196+
│ ├── confirm-dialog/ # Confirmation dialog modal
197+
│ ├── consent-form/ # Privacy consent form
198+
│ ├── error-boundary/ # Error boundary component
199+
│ ├── fire-button/ # Clear conversation data button
200+
│ ├── footer/ # Site footer
201+
│ ├── horizontal-rule/ # Visual separator component
202+
│ ├── main-heading/ # Main page heading
203+
│ ├── new-tab-label/ # Screen reader label for new tab links
204+
│ └── page-load-pixel/ # Page load event dispatcher
205+
├── config/ # Configuration constants
206+
│ ├── common.ts # Common site configuration
207+
│ ├── fonts.ts # Font configuration
208+
│ └── zendesk.ts # Zendesk widget configuration
209+
├── constants/ # Application constants
210+
│ ├── breakpoints.ts # Responsive breakpoint constants
211+
│ ├── footerLinks.ts # Footer link definitions
212+
│ ├── test-ids.ts # Test ID constants for Playwright tests
213+
│ ├── theme.ts # Theme constants and types
214+
│ ├── zendesk-selectors.ts # CSS selectors for Zendesk elements
215+
│ ├── zendesk-styles.ts # Custom CSS for Zendesk iframe
216+
│ └── zendesk-timing.ts # Timing constants for retries/delays
217+
├── contexts/ # React contexts
218+
│ └── theme-context.tsx # Theme context provider (system preference)
219+
├── hooks/ # React hooks
220+
│ ├── README.md # Documentation for Zendesk integration hooks
221+
│ ├── use-media-query.ts # Responsive design hook
222+
│ ├── use-zendesk-click-handlers.ts # Click event handlers
223+
│ ├── use-zendesk-iframe-styles.ts # Style injection
224+
│ └── use-zendesk-swap-article-links.ts # Article link swapping
225+
├── reducers/ # State reducers
226+
│ └── widget-reducer.ts # Widget lifecycle state reducer (zendeskReady, loadWidget, firstMessageSent)
227+
├── tests/ # Test files
228+
│ ├── fixtures/ # Test fixtures and mocks
229+
│ │ └── zendesk-mock.js # Zendesk widget mock for testing
230+
│ ├── integration/ # Integration tests
231+
│ │ └── complete-flow.test.ts # End-to-end user flow tests (9 tests)
232+
│ ├── unit/ # Unit tests
233+
│ │ ├── build-article-url.test.ts # URL building utility tests (3 tests)
234+
│ │ ├── get-slug-from-url.test.ts # URL slug extraction tests (3 tests)
235+
│ │ └── get-storage-with-expiry.test.ts # Storage expiry utility tests (13 tests)
236+
│ └── README.md # Testing documentation
237+
├── icons/ # SVG icon assets
238+
│ ├── logo-horizontal-dark.svg # DuckDuckGo logo (dark theme)
239+
│ ├── logo-horizontal-light.svg # DuckDuckGo logo (light theme)
240+
│ ├── logo-stacked-dark.svg # DuckDuckGo stacked logo (dark theme)
241+
│ └── logo-stacked-light.svg # DuckDuckGo stacked logo (light theme)
242+
├── types/ # TypeScript type definitions
243+
│ ├── lottie.ts # Lottie animation type definitions
244+
│ └── zendesk.d.ts # Extended Zendesk Web Widget types
245+
└── utils/ # Utility functions
246+
├── build-article-url.ts # URL building utility
247+
├── delete-storage-keys-by-suffix.ts # localStorage key deletion by suffix
248+
├── get-css-variable.ts # CSS variable reader
249+
├── get-slug-from-url.ts # URL slug extraction and sanitization
250+
├── get-storage-with-expiry.ts # localStorage retrieval with date expiry
251+
├── is-browser.ts # Browser environment detection (SSR safety)
252+
├── set-storage-with-expiry.ts # localStorage storage with date expiry
253+
├── cleanup-zendesk.ts # Zendesk widget cleanup utility
254+
├── update-article-links.ts # Link updating utility
255+
├── zendesk-iframe.ts # Iframe access utilities
256+
└── zendesk-observer.ts # MutationObserver setup utility
189257
```
190258

191259
## Deployment

‎src/tests/README.md‎

Lines changed: 34 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,11 @@ This project uses **Playwright** for all testing needs, with a focused test suit
77
## Test Results
88

99
```bash
10-
✅ 12 passing tests (~22s)
11-
- 3 unit tests (pure utility functions)
10+
✅ 19 passing tests (~22s)
11+
- 19 unit tests (pure utility functions)
12+
- 3 tests: build-article-url.test.ts
13+
- 3 tests: get-slug-from-url.test.ts
14+
- 13 tests: get-storage-with-expiry.test.ts
1215
- 9 integration tests (complete user flows)
1316
```
1417

@@ -18,12 +21,14 @@ This project uses **Playwright** for all testing needs, with a focused test suit
1821

1922
```
2023
src/tests/
21-
├── unit/ # Fast, isolated unit tests
22-
│ └── build-article-url.test.ts # Pure function tests
23-
├── integration/ # End-to-end integration tests
24-
│ └── complete-flow.test.ts # 🎯 COMPREHENSIVE FLOW TEST
24+
├── unit/ # Fast, isolated unit tests
25+
│ ├── build-article-url.test.ts # URL building utility tests
26+
│ ├── get-slug-from-url.test.ts # URL slug extraction tests
27+
│ └── get-storage-with-expiry.test.ts # Storage expiry utility tests
28+
├── integration/ # End-to-end integration tests
29+
│ └── complete-flow.test.ts # 🎯 COMPREHENSIVE FLOW TEST
2530
└── fixtures/
26-
└── zendesk-mock.js # Realistic Zendesk widget mock
31+
└── zendesk-mock.js # Realistic Zendesk widget mock
2732
```
2833

2934
## 🎯 Comprehensive Integration Test
@@ -58,7 +63,7 @@ The main integration test (`complete-flow.test.ts`) provides **high confidence**
5863
- Clicks send button
5964
- Confirms message was sent successfully
6065

61-
**4. ✅ Pixel Event Tracking**
66+
**4. ✅ Pixel Event Logging**
6267

6368
- Intercepts network calls to `https://improving.duckduckgo.com/t/*`
6469
- Verifies pixel events fire correctly:
@@ -286,7 +291,13 @@ test('should build URL correctly', () => {
286291
**Coverage:**
287292

288293
- `buildArticleUrl()` - URL construction with various path formats
289-
- Edge cases: leading/trailing slashes, empty paths, multiple segments
294+
- Edge cases: leading/trailing slashes, empty paths, multiple segments
295+
- `getSlugFromUrl()` - URL slug extraction and sanitization
296+
- Edge cases: invalid URLs, special characters, empty paths
297+
- `getStorageWithExpiry()` - localStorage retrieval with date-based expiry
298+
- Valid/invalid storage items, expired items, server-side handling
299+
- Date string format validation (YYYY-MM-DD)
300+
- Edge cases: missing keys, invalid JSON, type mismatches
290301

291302
### 2. Integration Tests (`src/tests/integration/`)
292303

@@ -327,9 +338,9 @@ test('complete flow', async ({ page }) => {
327338

328339
- Complete user journey: consent → script load → iframe render → hooks → interactions
329340
- Link swapping via `useZendeskSwapArticleLinks` hook
330-
- Click tracking via `useZendeskClickHandlers` hook
341+
- Click logging via `useZendeskClickHandlers` hook
331342
- Style injection via `useZendeskIframeStyles` hook
332-
- Pixel event tracking to `improving.duckduckgo.com`
343+
- Pixel event logging to `improving.duckduckgo.com`
333344
- Message sending and user interactions
334345
- Clear conversation data flow with dialog confirmation
335346
- Storage clearing (localStorage/sessionStorage)
@@ -502,7 +513,7 @@ When you add articles to `ARTICLE_LINK_MAP`:
502513

503514
### Adding New Pixel Events
504515

505-
When you add pixel tracking:
516+
When you add pixel logging:
506517

507518
1. **Add pixel call** in your component (e.g., `src/app/page.tsx`):
508519

@@ -585,14 +596,19 @@ test('should clear conversation data', async ({ page }) => {
585596
**Tests:**
586597

587598
- `src/tests/integration/complete-flow.test.ts` - Comprehensive integration tests (9 tests)
588-
- Complete widget flow with pixel tracking
599+
- Complete widget flow with pixel logging
589600
- Custom styles injection verification
590-
- Article link click tracking
591-
- Yes/No button click tracking
601+
- Article link click logging
602+
- Yes/No button click logging
592603
- Clear conversation data flow
593604
- Dialog cancellation flow
594-
- `src/tests/unit/build-article-url.test.ts` - Unit tests for utilities (3 tests)
595-
- `src/tests/unit/get-slug-from-url.test.ts` - Unit tests for utilities (3 tests)
605+
- `src/tests/unit/build-article-url.test.ts` - Unit tests for URL building utility (3 tests)
606+
- `src/tests/unit/get-slug-from-url.test.ts` - Unit tests for URL slug extraction (3 tests)
607+
- `src/tests/unit/get-storage-with-expiry.test.ts` - Unit tests for storage expiry utility (13 tests)
608+
- Valid/invalid storage items
609+
- Expired items handling
610+
- Server-side environment handling
611+
- Date string format validation
596612

597613
**Fixtures:**
598614

@@ -679,4 +695,4 @@ For issues or questions:
679695

680696
---
681697

682-
**Summary:** A focused test suite providing high confidence for CI deployment. Tests the complete user journey with realistic mocks, verifying iframe rendering, link swapping, message sending, pixel tracking, and the clear conversation data flow. Uses optimized helper functions to reduce duplication and improve maintainability.
698+
**Summary:** A focused test suite providing high confidence for CI deployment. Tests the complete user journey with realistic mocks, verifying iframe rendering, link swapping, message sending, pixel logging, and the clear conversation data flow. Uses optimized helper functions to reduce duplication and improve maintainability.

0 commit comments

Comments
 (0)