@mkhuda/dom-screenshot 0.0.1 → 1.0.1

package/tests/README.md

@@ -0,0 +1,394 @@
+# DOM Screenshot Testing Guide
+
+Complete testing setup for the dom-screenshot library using Vitest.
+
+## 📋 Directory Structure
+
+```
+tests/
+├── setup.ts                 # Global test setup and configuration
+├── README.md               # This file
+├── unit/                   # Unit tests
+│   └── basic.test.ts       # Basic functionality tests
+├── integration/            # Integration tests (coming soon)
+├── helpers/                # Test helper utilities
+│   └── dom-helpers.ts      # DOM manipulation helpers
+├── mocks/                  # Mock implementations
+│   ├── canvas-mock.ts      # Canvas API mocks
+│   ├── image-mock.ts       # Image loading mocks
+│   └── xhr-mock.ts         # XMLHttpRequest mocks
+└── fixtures/               # Test data and fixtures
+    ├── html.ts             # HTML test fixtures
+    ├── images.ts           # Image data URLs
+    └── styles.ts           # CSS and style fixtures
+```
+
+## 🚀 Quick Start
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+### Run Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests once (CI mode)
+npm run test:run
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with UI
+npm run test:ui
+
+# Generate coverage report
+npm run test:coverage
+```
+
+## 📝 Writing Tests
+
+### Basic Test Template
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { domtoimage } from '../../src/dom-screenshot';
+import { createSimpleDiv } from '../helpers/dom-helpers';
+
+describe('My Test Suite', () => {
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    if (container?.parentNode) {
+      container.parentNode.removeChild(container);
+    }
+  });
+
+  it('should do something', async () => {
+    const div = createSimpleDiv('Test');
+    const result = await domtoimage.toSvg(div);
+
+    expect(result).toBeValidSvgDataUrl();
+  });
+});
+```
+
+## 🛠️ Test Helpers
+
+### DOM Helpers (`helpers/dom-helpers.ts`)
+
+Create test DOM elements easily:
+
+```typescript
+import {
+  createSimpleDiv,
+  createStyledDiv,
+  createColoredDiv,
+  createImageElement,
+  createCanvasElement,
+  createComplexDOM,
+  createDOMWithStyles,
+  createSVGElement,
+  wait
+} from '../helpers/dom-helpers';
+
+// Create a simple div
+const div = createSimpleDiv('Hello');
+
+// Create styled div
+const styled = createStyledDiv('Content', { color: 'red' });
+
+// Create colored div
+const colored = createColoredDiv('Text', 'white', 'blue');
+
+// Create complex DOM tree
+const complex = createComplexDOM();
+```
+
+## 🎭 Mock Utilities
+
+### Canvas Mocks (`mocks/canvas-mock.ts`)
+
+Mock Canvas API operations:
+
+```typescript
+import {
+  mockCanvasToDataUrl,
+  mockCanvasToBlob,
+  mockCanvasContext,
+  createValidPngDataUrl,
+  createValidSvgDataUrl
+} from '../mocks/canvas-mock';
+
+// Mock canvas.toDataURL()
+mockCanvasToDataUrl(createValidPngDataUrl());
+
+// Mock canvas.toBlob()
+mockCanvasToBlob(new Blob(['data']));
+
+// Mock canvas context
+const { fillRect, drawImage } = mockCanvasContext();
+```
+
+### Image Mocks (`mocks/image-mock.ts`)
+
+Mock image loading:
+
+```typescript
+import {
+  mockImageSuccess,
+  mockImageError,
+  createImageDataUrl,
+  mockFileReaderDataUrl
+} from '../mocks/image-mock';
+
+// Mock successful image load
+mockImageSuccess(10); // 10ms delay
+
+// Mock image load error
+mockImageError(10);
+
+// Create image data URL
+const dataUrl = createImageDataUrl('png'); // or 'jpeg', 'gif'
+```
+
+### XHR Mocks (`mocks/xhr-mock.ts`)
+
+Mock XMLHttpRequest:
+
+```typescript
+import {
+  mockXhrSuccess,
+  mockXhrError,
+  mockXhrTimeout,
+  stubUrlPattern,
+  createBase64ImageData
+} from '../mocks/xhr-mock';
+
+// Mock successful XHR
+mockXhrSuccess('response-data', 10);
+
+// Mock XHR error
+mockXhrError(404, 10);
+
+// Mock XHR timeout
+mockXhrTimeout(100);
+
+// Stub specific URLs
+stubUrlPattern(
+  /example\.com\/image/,
+  'image-data',
+  200
+);
+```
+
+## 📦 Test Fixtures
+
+### HTML Fixtures (`fixtures/html.ts`)
+
+Pre-defined HTML strings for testing:
+
+```typescript
+import {
+  SIMPLE_HTML,
+  STYLED_HTML,
+  COMPLEX_HTML,
+  NESTED_HTML,
+  TEXT_HTML,
+  FORM_HTML,
+  COLOR_HTML,
+  BORDER_SHADOW_HTML,
+  MULTI_IMAGE_HTML,
+  TABLE_HTML,
+  SVG_HTML,
+  generateLargeHTML
+} from '../fixtures/html';
+
+// Use in tests
+container.innerHTML = SIMPLE_HTML;
+
+// Generate dynamic HTML
+const large = generateLargeHTML(100); // 100 items
+```
+
+### Image Fixtures (`fixtures/images.ts`)
+
+Pre-encoded image data URLs:
+
+```typescript
+import {
+  PNG_1X1_TRANSPARENT,
+  JPEG_1X1_RED,
+  GIF_1X1_BLUE,
+  SVG_CIRCLE,
+  TEST_IMAGES,
+  createTestImageElement,
+  createTestImageElements
+} from '../fixtures/images';
+
+// Use image data
+const img = new Image();
+img.src = PNG_1X1_TRANSPARENT;
+
+// Create test image elements
+const images = createTestImageElements(3);
+```
+
+### Style Fixtures (`fixtures/styles.ts`)
+
+Pre-defined CSS styles for testing:
+
+```typescript
+import {
+  CSS_FIXTURES,
+  createStyleElement,
+  createPseudoElementCSS,
+  createDivWithPseudoElements
+} from '../fixtures/styles';
+
+// Use CSS fixtures
+container.innerHTML = CSS_FIXTURES.gradientDiv;
+
+// Create pseudo-elements
+const div = createDivWithPseudoElements();
+```
+
+## 🧪 Custom Matchers
+
+Custom expect matchers are available:
+
+```typescript
+// Check for valid data URL
+expect(result).toBeValidDataUrl();
+
+// Check for valid SVG data URL
+expect(result).toBeValidSvgDataUrl();
+
+// Check for valid PNG data URL
+expect(result).toBeValidPngDataUrl();
+```
+
+## 📊 Test Coverage
+
+Generate coverage reports:
+
+```bash
+npm run test:coverage
+```
+
+Coverage reports are generated in:
+- `coverage/index.html` - HTML report
+- `coverage/lcov.info` - LCOV format (for CI/CD)
+- Console output - Summary
+
+## 🔍 Debugging Tests
+
+### Enable Debug Logging
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+
+describe('Debug Example', () => {
+  it('should log debug info', () => {
+    console.log('Debugging info here');
+    expect(true).toBe(true);
+  });
+});
+```
+
+### Run Single Test File
+
+```bash
+npx vitest tests/unit/basic.test.ts
+```
+
+### Run Single Test Suite
+
+```bash
+npx vitest -t "My Test Suite"
+```
+
+### Use Vitest UI
+
+```bash
+npm run test:ui
+```
+
+Opens an interactive UI at http://localhost:51204/__vitest__/
+
+## 🔄 Continuous Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npm install
+      - run: npm run test:run
+      - run: npm run test:coverage
+```
+
+## 📚 Testing Best Practices
+
+1. **Isolation**: Each test should be independent
+2. **Cleanup**: Always clean up DOM in `afterEach`
+3. **Mocking**: Mock external dependencies (Canvas, Image, XHR)
+4. **Fixtures**: Use fixtures for consistent test data
+5. **Naming**: Use descriptive test names
+6. **Assertions**: Use specific assertions, not generic `toBeTruthy()`
+7. **Async**: Always `await` promises and handle async operations
+8. **Performance**: Keep tests fast (< 100ms each if possible)
+
+## 🐛 Common Issues
+
+### Canvas Not Available
+Canvas is mocked in jsdom. Use `mockCanvasToDataUrl()` for PNG/JPEG tests.
+
+### Image Loading Fails
+Use `mockImageSuccess()` or `mockImageError()` to control image behavior.
+
+### XHR Requests Fail
+Use `mockXhrSuccess()`, `mockXhrError()`, or `stubUrlPattern()` to mock network requests.
+
+### Tests Timeout
+Increase timeout or mock async operations that have delays.
+
+## 📖 Resources
+
+- [Vitest Documentation](https://vitest.dev/)
+- [Chai Assertion Library](https://www.chaijs.com/)
+- [jsdom Documentation](https://github.com/jsdom/jsdom)
+- [Sinon.js Mocking](https://sinonjs.org/)
+
+## 🤝 Contributing
+
+When adding new features:
+
+1. Write tests first (TDD)
+2. Ensure all tests pass: `npm run test:run`
+3. Check coverage: `npm run test:coverage`
+4. Update this documentation
+5. Submit PR with tests
+
+---
+
+Happy testing! 🎉

package/tests/fixtures/html.ts

@@ -0,0 +1,192 @@
+/**
+ * HTML test fixtures
+ */
+
+/**
+ * Simple HTML fixture
+ */
+export const SIMPLE_HTML = `
+  <div style="width: 100px; height: 100px; background-color: blue;">
+    <p>Hello World</p>
+  </div>
+`;
+
+/**
+ * HTML with styled elements
+ */
+export const STYLED_HTML = `
+  <div style="
+    width: 200px;
+    height: 200px;
+    background: linear-gradient(to right, #ff0000, #00ff00);
+    border-radius: 10px;
+    padding: 20px;
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+  ">
+    <h1 style="color: white; font-size: 24px; margin: 0;">Styled Content</h1>
+    <p style="color: #f0f0f0; font-size: 14px;">This is a paragraph with custom styling.</p>
+  </div>
+`;
+
+/**
+ * HTML with various elements
+ */
+export const COMPLEX_HTML = `
+  <div style="width: 300px; background-color: #f5f5f5; padding: 20px;">
+    <h1>Title</h1>
+    <p>Paragraph text</p>
+    <ul>
+      <li>Item 1</li>
+      <li>Item 2</li>
+      <li>Item 3</li>
+    </ul>
+    <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" alt="test" style="width: 50px; height: 50px;" />
+  </div>
+`;
+
+/**
+ * HTML with nested divs
+ */
+export const NESTED_HTML = `
+  <div style="background-color: #ddd; padding: 10px;">
+    <div style="background-color: #ccc; padding: 10px;">
+      <div style="background-color: #bbb; padding: 10px;">
+        <p>Nested content</p>
+      </div>
+    </div>
+  </div>
+`;
+
+/**
+ * HTML with text and spans
+ */
+export const TEXT_HTML = `
+  <div style="font-family: Arial, sans-serif; font-size: 16px; line-height: 1.5;">
+    <p>This is <strong>bold</strong> text.</p>
+    <p>This is <em>italic</em> text.</p>
+    <p>This is <span style="color: red;">colored</span> text.</p>
+  </div>
+`;
+
+/**
+ * HTML with forms
+ */
+export const FORM_HTML = `
+  <div>
+    <form>
+      <input type="text" value="Test input" style="padding: 5px; border: 1px solid #ccc;" />
+      <textarea style="padding: 5px; border: 1px solid #ccc;">Test textarea value</textarea>
+      <button type="submit">Submit</button>
+    </form>
+  </div>
+`;
+
+/**
+ * HTML with colors
+ */
+export const COLOR_HTML = `
+  <div style="display: flex; gap: 10px;">
+    <div style="width: 50px; height: 50px; background-color: red;"></div>
+    <div style="width: 50px; height: 50px; background-color: green;"></div>
+    <div style="width: 50px; height: 50px; background-color: blue;"></div>
+    <div style="width: 50px; height: 50px; background-color: yellow;"></div>
+  </div>
+`;
+
+/**
+ * HTML with borders and shadows
+ */
+export const BORDER_SHADOW_HTML = `
+  <div style="
+    width: 150px;
+    height: 150px;
+    background-color: white;
+    border: 2px solid #333;
+    border-radius: 8px;
+    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);
+    padding: 15px;
+  ">
+    <p style="margin: 0; text-align: center;">Bordered & Shadowed</p>
+  </div>
+`;
+
+/**
+ * HTML with transformations
+ */
+export const TRANSFORM_HTML = `
+  <div style="
+    width: 100px;
+    height: 100px;
+    background-color: blue;
+    transform: rotate(45deg);
+  "></div>
+`;
+
+/**
+ * HTML with multiple images
+ */
+export const MULTI_IMAGE_HTML = `
+  <div style="display: flex; gap: 10px;">
+    <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" alt="img1" style="width: 50px; height: 50px;" />
+    <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" alt="img2" style="width: 50px; height: 50px;" />
+    <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" alt="img3" style="width: 50px; height: 50px;" />
+  </div>
+`;
+
+/**
+ * HTML with table
+ */
+export const TABLE_HTML = `
+  <table style="border-collapse: collapse; width: 200px;">
+    <tr style="background-color: #ddd;">
+      <th style="border: 1px solid #333; padding: 8px;">Column 1</th>
+      <th style="border: 1px solid #333; padding: 8px;">Column 2</th>
+    </tr>
+    <tr>
+      <td style="border: 1px solid #333; padding: 8px;">Data 1</td>
+      <td style="border: 1px solid #333; padding: 8px;">Data 2</td>
+    </tr>
+    <tr>
+      <td style="border: 1px solid #333; padding: 8px;">Data 3</td>
+      <td style="border: 1px solid #333; padding: 8px;">Data 4</td>
+    </tr>
+  </table>
+`;
+
+/**
+ * HTML with SVG
+ */
+export const SVG_HTML = `
+  <div>
+    <svg width="100" height="100" xmlns="http://www.w3.org/2000/svg">
+      <circle cx="50" cy="50" r="40" fill="blue" />
+      <rect x="10" y="10" width="30" height="30" fill="red" />
+    </svg>
+  </div>
+`;
+
+/**
+ * Empty div fixture
+ */
+export const EMPTY_HTML = `<div></div>`;
+
+/**
+ * Large HTML for performance testing
+ */
+export function generateLargeHTML(itemCount: number = 100): string {
+  let html = '<div style="background-color: #f5f5f5; padding: 10px;">';
+  for (let i = 0; i < itemCount; i++) {
+    html += `
+      <div style="
+        background-color: ${i % 2 === 0 ? '#fff' : '#ddd'};
+        padding: 5px;
+        margin: 5px;
+        border: 1px solid #ccc;
+      ">
+        <p>Item ${i + 1}</p>
+      </div>
+    `;
+  }
+  html += '</div>';
+  return html;
+}

package/tests/fixtures/images.ts

@@ -0,0 +1,86 @@
+/**
+ * Image test fixtures
+ */
+
+/**
+ * Base64-encoded 1x1 transparent PNG
+ */
+export const PNG_1X1_TRANSPARENT =
+  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+
+/**
+ * Base64-encoded 1x1 red JPEG
+ */
+export const JPEG_1X1_RED =
+  'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8VAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCwAA8A/9k=';
+
+/**
+ * Base64-encoded 1x1 blue GIF
+ */
+export const GIF_1X1_BLUE =
+  'data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==';
+
+/**
+ * SVG data URL
+ */
+export const SVG_CIRCLE =
+  'data:image/svg+xml;charset=utf-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22100%22%20height%3D%22100%22%3E%3Ccircle%20cx%3D%2250%22%20cy%3D%2250%22%20r%3D%2240%22%20fill%3D%22blue%22%2F%3E%3C%2Fsvg%3E';
+
+/**
+ * Invalid/broken image data URL
+ */
+export const INVALID_IMAGE_URL = 'data:image/png;base64,invalid-base64-data!!!';
+
+/**
+ * Remote image URL (would require network)
+ */
+export const REMOTE_IMAGE_URL = 'https://example.com/image.png';
+
+/**
+ * CORS-restricted image URL
+ */
+export const CORS_IMAGE_URL = 'https://other-domain.com/image.png';
+
+/**
+ * Collection of all test images
+ */
+export const TEST_IMAGES = {
+  png: PNG_1X1_TRANSPARENT,
+  jpeg: JPEG_1X1_RED,
+  gif: GIF_1X1_BLUE,
+  svg: SVG_CIRCLE,
+  invalid: INVALID_IMAGE_URL,
+  remote: REMOTE_IMAGE_URL,
+  cors: CORS_IMAGE_URL,
+};
+
+/**
+ * Create a test image HTML element
+ */
+export function createTestImageElement(
+  src: string = PNG_1X1_TRANSPARENT,
+  alt: string = 'test'
+): HTMLImageElement {
+  const img = document.createElement('img');
+  img.src = src;
+  img.alt = alt;
+  img.style.width = '50px';
+  img.style.height = '50px';
+  return img;
+}
+
+/**
+ * Create multiple test images
+ */
+export function createTestImageElements(count: number = 3): HTMLImageElement[] {
+  const images: HTMLImageElement[] = [];
+  const formats = ['png', 'jpeg', 'gif'] as const;
+
+  for (let i = 0; i < count; i++) {
+    const format = formats[i % formats.length];
+    const src = TEST_IMAGES[format];
+    images.push(createTestImageElement(src, `test-${i}`));
+  }
+
+  return images;
+}