feat: Use native Promises and improve automated tests

.github/workflows/ci.yml

@@ -1,17 +1,11 @@
 name: CI
 on: pull_request
 jobs:
-  vdiff:
-    name: Visual diff tests
+  unit:
+    name: Unit tests
     timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
-      - name: Create GH Token
-        uses: actions/create-github-app-token@v1
-        id: gh-token
-        with:
-          app-id: ${{ vars.GH_TOKEN_APP_ID }}
-          private-key: ${{ secrets.GH_TOKEN_APP_PRIVATE_KEY }}
       - name: Checkout
         uses: actions/checkout@v4
         with:
@@ -23,7 +17,24 @@ jobs:
           cache: npm
       - name: Install dependencies
         run: npm ci
+      - name: Unit tests
+        run: npm run test:unit
+
+  vdiff:
+    name: Visual diff tests
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
       - name: vdiff Tests
         uses: BrightspaceUI/actions/vdiff@main
         with:
-          github-token: ${{ steps.gh-token.outputs.token }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}

.nvmrc

@@ -1 +1 @@
-16
+22

.vdiff.json

@@ -0,0 +1,13 @@
+{
+	"browsers": [
+		{
+			"name": "Chromium",
+			"version": 139
+		}
+	],
+	"system": {
+		"platform": "linux",
+		"release": "6.11.0-1018-azure",
+		"arch": "x64"
+	}
+}

README.md

@@ -2,8 +2,6 @@
 
 html2pdf.js converts any webpage or element into a printable PDF entirely client-side using [html2canvas](https://github.com/niklasvh/html2canvas) and [jsPDF](https://github.com/MrRio/jsPDF).
 
-> :warning: There have been several issues reported in v0.10. They are being investigated but in the meantime you may wish to remain on v0.9.3 ("^0.9.3" in npm, or [use cdnjs for HTML script tags](https://cdnjs.com/libraries/html2pdf.js/0.9.3)).
-
 ## Table of contents
 
 - [Getting started](#getting-started)
@@ -231,19 +229,21 @@ The Worker object returned by `html2pdf()` has a built-in progress-tracking mech
 
 ## Dependencies
 
-html2pdf.js depends on the external packages [html2canvas](https://github.com/niklasvh/html2canvas), [jsPDF](https://github.com/MrRio/jsPDF), and [es6-promise](https://github.com/stefanpenner/es6-promise). These dependencies are automatically loaded when using NPM or the bundled package.
+html2pdf.js depends on the external packages [html2canvas](https://github.com/niklasvh/html2canvas) and [jsPDF](https://github.com/MrRio/jsPDF). These dependencies are automatically loaded when using NPM or the bundled package.
 
 If using the unbundled `dist/html2pdf.min.js` (or its un-minified version), you must also include each dependency. Order is important, otherwise html2canvas will be overridden by jsPDF's own internal implementation:
 
 ```html
-<script src="es6-promise.auto.min.js"></script>
 <script src="jspdf.min.js"></script>
 <script src="html2canvas.min.js"></script>
 <script src="html2pdf.min.js"></script>
 ```
 
 ## Contributing
 
+> [!TIP]
+> Working on html2pdf.js locally? Use `npm start` to host local demos on http://localhost:8000.
+
 ### Issues
 
 When submitting an issue, please provide reproducible code that highlights the issue, preferably by creating a fork of [this template jsFiddle](https://jsfiddle.net/u6o6ne41/) (which has html2pdf.js already loaded). Remember that html2pdf.js uses [html2canvas](https://github.com/niklasvh/html2canvas) and [jsPDF](https://github.com/MrRio/jsPDF) as dependencies, so it's a good idea to check each of those repositories' issue trackers to see if your problem has already been addressed.
@@ -269,7 +269,6 @@ When submitting an issue, please provide reproducible code that highlights the i
     - Related project: [Feature: New renderer](https://github.com/eKoopmans/html2pdf.js/projects/4)
 
 5. **Promise clashes:** html2pdf.js relies on specific Promise behaviour, and can fail when used with custom Promise libraries.
-    - In the next release, Promises will be sandboxed in html2pdf.js to remove this issue.
     - Related project: [Bugfix: Sandboxed promises](https://github.com/eKoopmans/html2pdf.js/projects/11)
 
 6. **Maximum size:** HTML5 canvases have a [maximum height/width](https://stackoverflow.com/a/11585939/4080966). Anything larger will fail to render.
@@ -279,7 +278,7 @@ When submitting an issue, please provide reproducible code that highlights the i
 
 ### Tests
 
-html2pdf.js is currently sorely lacking in unit tests. Any contributions or suggestions of automated (or manual) tests are welcome. This is high on the to-do list for this project.
+html2pdf.js performs automatic vdiff (visual difference) comparisons on PDFs generated from a collection of sample HTML files. Contributions of additional test cases are more than welcome - see `test/vdiff/html2pdf.vdiff.js` and `test/reference/*.html` for examples. Some changes may require adding more options to the test harness, `test/util/test-harness.js`.
 
 ### Pull requests
 

demo/all-tags.html

@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+		<meta charset="UTF-8">
+		<link rel="stylesheet" href="/node_modules/@brightspace-ui/core/components/demo/styles.css" type="text/css">
+		<script type="module">
+			import '@brightspace-ui/core/components/demo/demo-page.js';
+            import '../test/util/test-harness.js';
+		</script>
+	</head>
+
+	<body unresolved>
+		<d2l-demo-page page-title="html2pdf.js - All tags">
+			<h2>All tags: default</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="all-tags"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+
+			<h2>All tags: #canvas selector</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="all-tags"
+						selector="#canvas"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+		</d2l-demo-page>
+	</body>
+</html>

demo/blank.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+		<meta charset="UTF-8">
+		<link rel="stylesheet" href="/node_modules/@brightspace-ui/core/components/demo/styles.css" type="text/css">
+		<script type="module">
+			import '@brightspace-ui/core/components/demo/demo-page.js';
+            import '../test/util/test-harness.js';
+		</script>
+	</head>
+
+	<body unresolved>
+		<d2l-demo-page page-title="html2pdf.js - Blank">
+			<h2>Blank page: default</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="blank"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+        </d2l-demo-page>
+	</body>
+</html>

demo/css-selectors.html

@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+		<meta charset="UTF-8">
+		<link rel="stylesheet" href="/node_modules/@brightspace-ui/core/components/demo/styles.css" type="text/css">
+		<script type="module">
+			import '@brightspace-ui/core/components/demo/demo-page.js';
+            import '../test/util/test-harness.js';
+		</script>
+	</head>
+
+	<body unresolved>
+		<d2l-demo-page page-title="html2pdf.js - CSS selectors">
+			<h2>CSS selectors: default</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="css-selectors"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+
+			<h2>CSS selectors: #main selector</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="css-selectors"
+						selector="#main"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+		</d2l-demo-page>
+	</body>
+</html>

demo/index.html

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<link rel="stylesheet" href="/node_modules/@brightspace-ui/core/components/demo/styles.css" type="text/css">
+	<script type="module">
+		import '@brightspace-ui/core/components/colors/colors.js';
+		import '@brightspace-ui/core/components/typography/typography.js';
+	</script>
+	<title>html2pdf.js Demos</title>
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<meta charset="UTF-8">
+	<style>
+		body {
+			padding: 0 30px;
+		}
+	</style>
+</head>
+<body class="d2l-typography">
+    <h1 class="d2l-heading-2">html2pdf.js Demos</h1>
+
+    <h2 class="d2l-heading-3">Manual testing</h2>
+    <ul>
+        <li><a href="../test/manual/launcher.html">html2pdf.js Launcher</a></li>
+        <li><a href="../test/manual/pagebreaks.html">Pagebreaks</a></li>
+        <li><a href="../test/manual/template.html">Template</a></li>
+    </ul>
+
+    <h2 class="d2l-heading-3">Test harness demos (requires local serving with `npm start`)</h2>
+    <ul>
+        <li><a href="./all-tags.html">All tags</a></li>
+        <li><a href="./blank.html">Blank</a></li>
+        <li><a href="./css-selectors.html">CSS selectors</a></li>
+        <li><a href="./lorem-ipsum.html">Lorem ipsum</a></li>
+        <li><a href="./pagebreaks.html">Pagebreaks</a></li>
+    </ul>
+</body>

demo/lorem-ipsum.html

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+		<meta charset="UTF-8">
+		<link rel="stylesheet" href="/node_modules/@brightspace-ui/core/components/demo/styles.css" type="text/css">
+		<script type="module">
+			import '@brightspace-ui/core/components/demo/demo-page.js';
+            import '../test/util/test-harness.js';
+		</script>
+	</head>
+
+	<body unresolved>
+		<d2l-demo-page page-title="html2pdf.js - Lorem ipsum">
+			<h2>Lorem ipsum: default</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="lorem-ipsum"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+
+			<h2>Lorem ipsum: legacy command</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+						command="legacy"
+                        controls
+                        file="lorem-ipsum"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+
+			<h2>Lorem ipsum: margin</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="lorem-ipsum"
+						settings="margin"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+		</d2l-demo-page>
+	</body>
+</html>

demo/pagebreaks.html

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+		<meta charset="UTF-8">
+		<link rel="stylesheet" href="/node_modules/@brightspace-ui/core/components/demo/styles.css" type="text/css">
+		<script type="module">
+			import '@brightspace-ui/core/components/demo/demo-page.js';
+            import '../test/util/test-harness.js';
+		</script>
+	</head>
+
+	<body unresolved>
+		<d2l-demo-page page-title="html2pdf.js - Pagebreaks">
+			<h2>Pagebreaks: legacy</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="pagebreaks"
+						settings="pagebreakLegacy"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+
+			<h2>Pagebreaks: CSS</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="pagebreaks"
+						settings="pagebreakCss"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+
+			<h2>Pagebreaks: avoid-all</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="pagebreaks"
+						settings="pagebreakAvoidAll"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+
+			<h2>Pagebreaks: specify</h2>
+			<d2l-demo-snippet>
+				<template>
+                    <test-harness
+                        controls
+                        file="pagebreaks"
+						settings="pagebreakSpecify"
+                    ></test-harness>
+				</template>
+			</d2l-demo-snippet>
+		</d2l-demo-page>
+	</body>
+</html>