@mkhuda/dom-screenshot 0.0.2 → 1.0.1

package/TEST_SETUP_SUMMARY.md

@@ -0,0 +1,335 @@
+# Complete Test Setup Summary
+
+## ✅ What Was Created
+
+### 🎯 Configuration Files
+1. **vitest.config.ts** - Complete Vitest configuration with jsdom environment
+2. **tests/setup.ts** - Global test setup with:
+   - Chai with Promise support
+   - Sinon sandbox management
+   - Custom matchers (toBeValidDataUrl, toBeValidSvgDataUrl, toBeValidPngDataUrl)
+   - DOM cleanup
+
+### 📦 Dependencies Installed
+```
+- vitest@^4.0.8          (Fast unit test framework)
+- jsdom@^27.1.0          (DOM simulation)
+- chai@^6.2.0            (Assertions)
+- chai-as-promised@^8.0.2 (Promise assertions)
+- sinon@^21.0.0          (Spies, stubs, mocks)
+- nock@^14.0.10          (HTTP mocking)
+- @testing-library/dom@^10.4.1 (DOM utilities)
+- @vitest/coverage-v8@^4.0.8 (Coverage reporting)
+- @vitest/ui@^4.0.8      (Visual test UI)
+```
+
+### 🛠️ Helper Utilities Created
+
+#### 1. **tests/helpers/dom-helpers.ts**
+- `createSimpleDiv()` - Simple div with text
+- `createStyledDiv()` - Div with custom CSS
+- `createColoredDiv()` - Colored text and background
+- `createImageElement()` - Image element
+- `createCanvasElement()` - Canvas with drawing
+- `createVideoElement()` - Video element
+- `createTextarea()` - Textarea with value
+- `createInput()` - Input with value
+- `createComplexDOM()` - Multi-element tree
+- `createDOMWithStyles()` - Advanced styling
+- `createDOMWithPseudoElements()` - With ::before/::after
+- `createSVGElement()` - SVG element
+- `wait()` - Promise delay
+- `parseDataUrl()` - Parse data URLs
+- `isValidDataUrl()` - Validate data URL
+- `isImageDataUrl()` - Validate image data URL
+
+#### 2. **tests/mocks/canvas-mock.ts**
+- `mockCanvasToDataUrl()` - Mock canvas.toDataURL()
+- `mockCanvasToBlob()` - Mock canvas.toBlob()
+- `mockCanvasContext()` - Mock canvas context
+- `createValidPngDataUrl()` - Generate valid PNG data URL
+- `createValidJpegDataUrl()` - Generate valid JPEG data URL
+- `createValidSvgDataUrl()` - Generate valid SVG data URL
+- `mockCanvasDataUrls()` - Create multiple format URLs
+
+#### 3. **tests/mocks/image-mock.ts**
+- `mockImageSuccess()` - Mock successful image load
+- `mockImageError()` - Mock image load error
+- `mockImageCustom()` - Custom image behavior
+- `createImageDataUrl()` - Create image data URL
+- `stubImageXhr()` - Mock XHR for images
+- `mockFileReaderDataUrl()` - Mock FileReader
+
+#### 4. **tests/mocks/xhr-mock.ts**
+- `mockXhrSuccess()` - Mock successful XHR
+- `mockXhrError()` - Mock XHR error (404, etc)
+- `mockXhrTimeout()` - Mock XHR timeout
+- `stubUrlPattern()` - Mock specific URL patterns
+- `createBase64ImageData()` - Create image data
+
+### 📦 Test Fixtures Created
+
+#### 1. **tests/fixtures/html.ts** (12 HTML fixtures)
+- `SIMPLE_HTML` - Basic div
+- `STYLED_HTML` - With gradient, shadow, etc
+- `COMPLEX_HTML` - Multiple elements
+- `NESTED_HTML` - Nested divs
+- `TEXT_HTML` - Text formatting
+- `FORM_HTML` - Form elements
+- `COLOR_HTML` - Color blocks
+- `BORDER_SHADOW_HTML` - Borders & shadows
+- `TRANSFORM_HTML` - CSS transforms
+- `MULTI_IMAGE_HTML` - Multiple images
+- `TABLE_HTML` - HTML table
+- `SVG_HTML` - SVG elements
+- `EMPTY_HTML` - Empty div
+- `generateLargeHTML()` - Dynamic large HTML
+
+#### 2. **tests/fixtures/images.ts** (7 image fixtures)
+- `PNG_1X1_TRANSPARENT` - 1x1 PNG
+- `JPEG_1X1_RED` - 1x1 JPEG
+- `GIF_1X1_BLUE` - 1x1 GIF
+- `SVG_CIRCLE` - SVG circle
+- `INVALID_IMAGE_URL` - Broken image
+- `REMOTE_IMAGE_URL` - HTTP URL
+- `CORS_IMAGE_URL` - CORS URL
+- `TEST_IMAGES` - Collection object
+- `createTestImageElement()` - Create img element
+- `createTestImageElements()` - Create multiple imgs
+
+#### 3. **tests/fixtures/styles.ts** (12 CSS fixtures)
+- `CSS_FIXTURES` - Pre-built CSS examples:
+  - coloredDiv
+  - gradientDiv
+  - borderShadowDiv
+  - borderRadiusDiv
+  - transformDiv
+  - opacityDiv
+  - fontStyledDiv
+  - flexboxDiv
+  - gridDiv
+  - spacingDiv
+  - textAlignDiv
+  - overflowDiv
+  - listDiv
+  - tableDiv
+- `createStyleElement()` - Create style tag
+- `createPseudoElementCSS()` - Pseudo-element CSS
+- `createDivWithPseudoElements()` - Div with ::before/::after
+
+### 🧪 Sample Tests
+
+#### **tests/unit/basic.test.ts** (Complete working example)
+Tests for:
+- ✅ toSvg() - SVG conversion
+- ✅ toPng() - PNG conversion
+- ✅ toJpeg() - JPEG conversion
+- ✅ toBlob() - Blob conversion
+- ✅ toPixelData() - Pixel data extraction
+- ✅ Options (bgcolor, width, height, style, filter, quality)
+- ✅ Error handling
+- ✅ HTML integration
+- ✅ Complex DOM handling
+
+### 📚 Documentation
+
+1. **tests/README.md** - Comprehensive testing guide
+   - Directory structure
+   - Quick start commands
+   - Writing tests
+   - Helper usage
+   - Mock usage
+   - Fixture usage
+   - Custom matchers
+   - Coverage reporting
+   - Debugging tips
+   - CI/CD examples
+   - Best practices
+
+2. **TESTING.md** - Quick reference guide
+   - Quick commands
+   - Structure overview
+   - First test example
+   - Mocking examples
+   - Fixture examples
+   - Custom matchers
+   - Common mistakes
+
+## 🚀 Available Commands
+
+```bash
+npm test              # Run tests (watch mode)
+npm run test:run      # Run tests once
+npm run test:ui       # Open visual UI
+npm run test:watch    # Run in watch mode
+npm run test:coverage # Generate coverage report
+```
+
+## 📂 File Tree
+
+```
+├── vitest.config.ts              ✨ New
+├── TESTING.md                    ✨ New
+├── TEST_SETUP_SUMMARY.md         ✨ New
+└── tests/                        ✨ New
+    ├── README.md                 📖 Documentation
+    ├── setup.ts                  ⚙️  Global setup
+    ├── unit/
+    │   └── basic.test.ts         ✅ Sample tests
+    ├── integration/              (coming soon)
+    ├── helpers/
+    │   └── dom-helpers.ts        🛠️  DOM utilities
+    ├── mocks/
+    │   ├── canvas-mock.ts        🎭 Canvas mocks
+    │   ├── image-mock.ts         📸 Image mocks
+    │   └── xhr-mock.ts           🌐 Network mocks
+    └── fixtures/
+        ├── html.ts               📝 HTML fixtures
+        ├── images.ts             🖼️  Image fixtures
+        └── styles.ts             🎨 CSS fixtures
+```
+
+## 🎯 Testing Stack
+
+| Component | Package | Version | Purpose |
+|-----------|---------|---------|---------|
+| Test Runner | vitest | ^4.0.8 | Fast, ESM-native test runner |
+| DOM | jsdom | ^27.1.0 | DOM simulation for Node.js |
+| Assertions | chai | ^6.2.0 | Assertion library |
+| Promises | chai-as-promised | ^8.0.2 | Promise assertions |
+| Mocking | sinon | ^21.0.0 | Spies, stubs, mocks |
+| DOM Testing | @testing-library/dom | ^10.4.1 | DOM utilities |
+| HTTP Mocking | nock | ^14.0.10 | HTTP interception |
+| Coverage | @vitest/coverage-v8 | ^4.0.8 | Code coverage |
+| UI | @vitest/ui | ^4.0.8 | Visual dashboard |
+
+## 🎓 What You Can Do Now
+
+### ✅ Quick Start
+```bash
+npm test
+```
+Runs tests in watch mode - perfect for development!
+
+### ✅ Write Tests
+```bash
+# Create new test file
+# tests/unit/my-feature.test.ts
+
+import { describe, it, expect } from 'vitest';
+import { domtoimage } from '../../src/dom-screenshot';
+import { createStyledDiv } from '../helpers/dom-helpers';
+
+describe('My Feature', () => {
+  it('should work', async () => {
+    const div = createStyledDiv('Test', { backgroundColor: 'blue' });
+    const result = await domtoimage.toSvg(div);
+    expect(result).toBeValidSvgDataUrl();
+  });
+});
+```
+
+### ✅ Mock External Dependencies
+```typescript
+import { mockCanvasToDataUrl, createValidPngDataUrl } from '../mocks/canvas-mock';
+import { mockImageSuccess } from '../mocks/image-mock';
+
+beforeEach(() => {
+  mockCanvasToDataUrl(createValidPngDataUrl());
+  mockImageSuccess(10);
+});
+```
+
+### ✅ Use Test Fixtures
+```typescript
+import { SIMPLE_HTML, PNG_1X1_TRANSPARENT, CSS_FIXTURES } from '../fixtures';
+
+container.innerHTML = SIMPLE_HTML;
+const img = new Image();
+img.src = PNG_1X1_TRANSPARENT;
+```
+
+### ✅ Generate Coverage
+```bash
+npm run test:coverage
+# Opens: coverage/index.html
+```
+
+### ✅ Visual Debugging
+```bash
+npm run test:ui
+# Opens: http://localhost:51204/__vitest__/
+```
+
+## 🔄 Next Steps
+
+1. **Run the sample tests**
+   ```bash
+   npm test
+   ```
+
+2. **Read the documentation**
+   - [TESTING.md](./TESTING.md) - Quick reference
+   - [tests/README.md](./tests/README.md) - Comprehensive guide
+
+3. **Write your own tests**
+   - Create `tests/unit/my-feature.test.ts`
+   - Use helpers, mocks, and fixtures
+   - Run with `npm test`
+
+4. **Expand test coverage**
+   - Add integration tests
+   - Test edge cases
+   - Test error scenarios
+
+## 📊 Test Categories Ready to Write
+
+### Unit Tests (Ready Now)
+- ✅ Utility functions
+- ✅ Single DOM elements
+- ✅ Format conversions
+- ✅ Options handling
+- ✅ Error cases
+
+### Integration Tests (Structure Ready)
+- Complex DOM trees
+- Multiple resources
+- Style inheritance
+- Font loading
+- Image inlining
+
+### E2E Tests (Future)
+- Real browser testing
+- Visual regression
+- Performance benchmarks
+
+## 🎉 Summary
+
+**Complete testing infrastructure is now in place:**
+- ✅ Test runner configured
+- ✅ Mock utilities created
+- ✅ Test fixtures prepared
+- ✅ Helper utilities built
+- ✅ Sample tests written
+- ✅ Documentation provided
+- ✅ npm scripts added
+
+**You can now:**
+- Write unit tests with confidence
+- Mock Canvas, Image, and XHR
+- Use pre-built fixtures
+- Generate coverage reports
+- Debug with visual UI
+
+**Total files created:** 10
+- Configuration: 1
+- Setup: 1
+- Helpers: 1
+- Mocks: 3
+- Fixtures: 3
+- Tests: 1
+- Documentation: 3
+
+---
+
+**Ready to test!** Run `npm test` to get started. 🚀

package/dist/dom-screenshot.d.ts

@@ -1,277 +1,49 @@
+import type { DomScreenshotOptions } from './types/options';
 /**
- * @param {Node} node - The DOM Node object to render
- * @param {Options} options - Rendering options
- * @return {Promise} - A promise that is fulfilled with a SVG image data URL
- * */
-export function toSvg(node: Node, options: {
-    /**
-     * - Should return true if passed node should be included in the output
-     * (excluding node means excluding it's children as well). Not called on the root node.
-     */
-    filter?: Function | undefined;
-    /**
-     * - color for the background, any valid CSS color value.
-     */
-    bgcolor?: string | undefined;
-    /**
-     * - width to be applied to node before rendering.
-     */
-    width?: number | undefined;
-    /**
-     * - height to be applied to node before rendering.
-     */
-    height?: number | undefined;
-    /**
-     * - an object whose properties to be copied to node's style before rendering.
-     */
-    style?: any | undefined;
-    /**
-     * - a Number between 0 and 1 indicating image quality (applicable to JPEG only),
-     * defaults to 1.0.
-     */
-    quality?: number | undefined;
-    /**
-     * - dataURL to use as a placeholder for failed images, default behaviour is to fail fast on images we can't fetch
-     */
-    imagePlaceholder?: string | undefined;
-    /**
-     * - set to true to cache bust by appending the time to the request url
-     */
-    cacheBust?: boolean;
-}): Promise<any>;
+ * Main domtoimage module export
+ */
+export declare const domtoimage: {
+    toSvg: typeof toSvg;
+    toPng: typeof toPng;
+    toJpeg: typeof toJpeg;
+    toBlob: typeof toBlob;
+    toPixelData: typeof toPixelData;
+    impl: any;
+};
+export { toSvg, toPng, toJpeg, toBlob, toPixelData };
 /**
- * @param {Node} node - The DOM Node object to render
- * @param {Options} options - Rendering options
- * @return {Promise} - A promise that is fulfilled with a PNG image data URL
- * */
-export function toPng(node: Node, options: {
-    /**
-     * - Should return true if passed node should be included in the output
-     * (excluding node means excluding it's children as well). Not called on the root node.
-     */
-    filter?: Function | undefined;
-    /**
-     * - color for the background, any valid CSS color value.
-     */
-    bgcolor?: string | undefined;
-    /**
-     * - width to be applied to node before rendering.
-     */
-    width?: number | undefined;
-    /**
-     * - height to be applied to node before rendering.
-     */
-    height?: number | undefined;
-    /**
-     * - an object whose properties to be copied to node's style before rendering.
-     */
-    style?: any | undefined;
-    /**
-     * - a Number between 0 and 1 indicating image quality (applicable to JPEG only),
-     * defaults to 1.0.
-     */
-    quality?: number | undefined;
-    /**
-     * - dataURL to use as a placeholder for failed images, default behaviour is to fail fast on images we can't fetch
-     */
-    imagePlaceholder?: string | undefined;
-    /**
-     * - set to true to cache bust by appending the time to the request url
-     */
-    cacheBust?: boolean;
-}): Promise<any>;
+ * Render DOM node to SVG data URL
+ * @param node - The DOM Node object to render
+ * @param options - Rendering options
+ * @returns Promise fulfilled with a SVG image data URL
+ */
+declare function toSvg(node: Node, options?: DomScreenshotOptions): Promise<string>;
 /**
- * @param {Node} node - The DOM Node object to render
- * @param {Options} options - Rendering options
- * @return {Promise} - A promise that is fulfilled with a JPEG image data URL
- * */
-export function toJpeg(node: Node, options: {
-    /**
-     * - Should return true if passed node should be included in the output
-     * (excluding node means excluding it's children as well). Not called on the root node.
-     */
-    filter?: Function | undefined;
-    /**
-     * - color for the background, any valid CSS color value.
-     */
-    bgcolor?: string | undefined;
-    /**
-     * - width to be applied to node before rendering.
-     */
-    width?: number | undefined;
-    /**
-     * - height to be applied to node before rendering.
-     */
-    height?: number | undefined;
-    /**
-     * - an object whose properties to be copied to node's style before rendering.
-     */
-    style?: any | undefined;
-    /**
-     * - a Number between 0 and 1 indicating image quality (applicable to JPEG only),
-     * defaults to 1.0.
-     */
-    quality?: number | undefined;
-    /**
-     * - dataURL to use as a placeholder for failed images, default behaviour is to fail fast on images we can't fetch
-     */
-    imagePlaceholder?: string | undefined;
-    /**
-     * - set to true to cache bust by appending the time to the request url
-     */
-    cacheBust?: boolean;
-}): Promise<any>;
+ * Render DOM node to PNG data URL
+ * @param node - The DOM Node object to render
+ * @param options - Rendering options
+ * @returns Promise fulfilled with a PNG image data URL
+ */
+declare function toPng(node: Node, options?: DomScreenshotOptions): Promise<string>;
 /**
- * @param {Node} node - The DOM Node object to render
- * @param {Options} options - Rendering options
- * @return {Promise} - A promise that is fulfilled with a Blob image data URL
- * */
-export function toBlob(node: Node, options: {
-    /**
-     * - Should return true if passed node should be included in the output
-     * (excluding node means excluding it's children as well). Not called on the root node.
-     */
-    filter?: Function | undefined;
-    /**
-     * - color for the background, any valid CSS color value.
-     */
-    bgcolor?: string | undefined;
-    /**
-     * - width to be applied to node before rendering.
-     */
-    width?: number | undefined;
-    /**
-     * - height to be applied to node before rendering.
-     */
-    height?: number | undefined;
-    /**
-     * - an object whose properties to be copied to node's style before rendering.
-     */
-    style?: any | undefined;
-    /**
-     * - a Number between 0 and 1 indicating image quality (applicable to JPEG only),
-     * defaults to 1.0.
-     */
-    quality?: number | undefined;
-    /**
-     * - dataURL to use as a placeholder for failed images, default behaviour is to fail fast on images we can't fetch
-     */
-    imagePlaceholder?: string | undefined;
-    /**
-     * - set to true to cache bust by appending the time to the request url
-     */
-    cacheBust?: boolean;
-}): Promise<any>;
+ * Render DOM node to JPEG data URL
+ * @param node - The DOM Node object to render
+ * @param options - Rendering options
+ * @returns Promise fulfilled with a JPEG image data URL
+ */
+declare function toJpeg(node: Node, options?: DomScreenshotOptions): Promise<string>;
 /**
- * @param {Node} node - The DOM Node object to render
- * @param {Options} options - Rendering options
- * @return {Promise} - A promise that is fulfilled with a PixelData image data URL
- * */
-export function toPixelData(node: Node, options: {
-    /**
-     * - Should return true if passed node should be included in the output
-     * (excluding node means excluding it's children as well). Not called on the root node.
-     */
-    filter?: Function | undefined;
-    /**
-     * - color for the background, any valid CSS color value.
-     */
-    bgcolor?: string | undefined;
-    /**
-     * - width to be applied to node before rendering.
-     */
-    width?: number | undefined;
-    /**
-     * - height to be applied to node before rendering.
-     */
-    height?: number | undefined;
-    /**
-     * - an object whose properties to be copied to node's style before rendering.
-     */
-    style?: any | undefined;
-    /**
-     * - a Number between 0 and 1 indicating image quality (applicable to JPEG only),
-     * defaults to 1.0.
-     */
-    quality?: number | undefined;
-    /**
-     * - dataURL to use as a placeholder for failed images, default behaviour is to fail fast on images we can't fetch
-     */
-    imagePlaceholder?: string | undefined;
-    /**
-     * - set to true to cache bust by appending the time to the request url
-     */
-    cacheBust?: boolean;
-}): Promise<any>;
-declare namespace fontFaces {
-    export { resolveAll };
-    export namespace impl_1 {
-        export { readAll };
-    }
-    export { impl_1 as impl };
-}
-declare namespace images {
-    export { inlineAll };
-    export namespace impl_2 {
-        export { newImage };
-    }
-    export { impl_2 as impl };
-}
-declare namespace util {
-    export { escapeMain };
-    export { parseExtension };
-    export { mimeType };
-    export { dataAsUrl };
-    export { isDataUrl };
-    export { canvasToBlob };
-    export { resolveUrl };
-    export { getAndEncode };
-    export function uid(): string;
-    export { delay };
-    export { asArray };
-    export { escapeXhtml };
-    export { makeImage };
-    export { width };
-    export { height };
-}
-declare namespace inliner {
-    export { inlineAll };
-    export { shouldProcess };
-    export namespace impl_3 {
-        export { readUrls };
-        export { inline };
-    }
-    export { impl_3 as impl };
-}
-declare function resolveAll(): Promise<string>;
-declare function readAll(): Promise<any>;
-declare function inlineAll(node: any): any;
-declare function newImage(element: any): {
-    inline: (get: any) => Promise<any>;
-};
-declare function escapeMain(string: any): any;
-declare function parseExtension(url: any): string;
-declare function mimeType(url: any): any;
-declare function dataAsUrl(content: any, type: any): string;
-declare function isDataUrl(url: any): boolean;
-declare function canvasToBlob(canvas: any): Promise<any>;
-declare function resolveUrl(url: any, baseUrl: any): string;
-declare function getAndEncode(url: any): Promise<any>;
-declare function delay(ms: any): (arg: any) => Promise<any>;
-declare function asArray(arrayLike: any): any[];
-declare function escapeXhtml(string: any): any;
-declare function makeImage(uri: any): Promise<any>;
-declare function width(node: any): any;
-declare function height(node: any): any;
-declare function inlineAll_1(string: any, baseUrl: any, get: any): Promise<any>;
-declare function shouldProcess(string: any): boolean;
-declare function readUrls(string: any): string[];
-declare function inline(string: any, url: any, baseUrl: any, get: any): Promise<any>;
-export declare namespace impl {
-    export { fontFaces };
-    export { images };
-    export { util };
-    export { inliner };
-    export const options: {};
-}
-export {};
+ * Render DOM node to Blob
+ * @param node - The DOM Node object to render
+ * @param options - Rendering options
+ * @returns Promise fulfilled with a Blob
+ */
+declare function toBlob(node: Node, options?: DomScreenshotOptions): Promise<Blob>;
+/**
+ * Render DOM node to PixelData
+ * @param node - The DOM Node object to render
+ * @param options - Rendering options
+ * @returns Promise fulfilled with pixel data array
+ */
+declare function toPixelData(node: Node, options?: DomScreenshotOptions): Promise<Uint8ClampedArray>;
+//# sourceMappingURL=dom-screenshot.d.ts.map

package/dist/dom-screenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-screenshot.d.ts","sourceRoot":"","sources":["../src/dom-screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAUrB,MAAM,iBAAiB,CAAC;AAazB;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;UAMT,GAAG;CAChB,CAAC;AAeF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AAErD;;;;;GAKG;AACH,iBAAS,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoC1E;AAED;;;;;GAKG;AACH,iBAAS,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAI1E;AAED;;;;;GAKG;AACH,iBAAS,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAK3E;AAED;;;;;GAKG;AACH,iBAAS,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKzE;AAED;;;;;GAKG;AACH,iBAAS,WAAW,CAClB,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAO5B"}