@markedjs/testutils 9.1.0-0 → 9.1.0-2

package/README.md

@@ -1,3 +1,111 @@
 # @markedjs/testutils
 
-Test utilities for marked and marked extensions
+Test utilities for marked and marked extensions.
+
+## Versioning
+
+This is versioned as the version of marked that it includes tests for with the prerelease version being an integer that gets incremented when we release a new fix or feature without updating the marked version.
+
+We recommend to pin to a single version instead of using a range since any update may contain breaking changes.
+
+**Example**
+
+```json
+// package.json
+"dependencies": {
+  "@markedjs/testutils": "9.1.0-0"
+}
+```
+
+## API
+
+### `getAllMarkedSpecTests()`
+
+Get all marked [Tests](#tests)
+
+### `getTests(dirs)`
+
+Get [Tests](#tests) from a directory or file.
+`dirs` can be a string or an array of strings.
+The return type is the same as the input a Tests object or an array of Tests objects.
+
+### `htmlIsEqual(actual, expected)`
+
+Check if html will display the same.
+
+### `firstDiff(actual, expected, padding)`
+
+Get the first difference between actual and expected HTML. Returns an object with the characters around the index of the first difference in the expected and actual strings.
+
+### `outputCompletionTable(title, tests)`
+
+Display a table in stdout that lists the sections and what percentage of the tests are not marked shouldFail.
+
+### `runTests({tests, defaultMarkedOptions, parse, addExtension, isEqual, diff})`
+
+Run spec tests
+
+### `runAllMarkedSpecTests({addExtension, outputCompletionTables})`
+
+Run all marked specs with an added extension and optionally output completion table.
+
+## Arguments
+
+### tests
+
+```ts
+interface Tests {
+  total: number;
+  pass: number;
+  specs: Spec[];
+}
+
+interface Spec {
+  section?: string;
+  markdown: string;
+  html: string;
+  example?: number;
+  options?: MarkedOptions;
+  only?: boolean;
+  skip?: boolean;
+  shouldFail?: boolean;
+}
+```
+
+### defaultMarkedOptions
+
+```ts
+type defaultMarkedOptions = MarkedOptions;
+```
+
+### parse
+
+```ts
+function parse(
+  markdown: string,
+  options: MarkedOptions,
+  addExtension: addExtension,
+): string;
+```
+
+### addExtension
+
+```ts
+function addExtension(marked: Marked): void;
+```
+
+### isEqual
+
+```ts
+function isEqual(actual: string, expected: string): boolean;
+```
+
+### diff
+
+```ts
+function diff(
+  actual: string,
+  expected: string,
+  padding: number,
+): { expected: string; actual: string };
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markedjs/testutils",
-  "version": "9.1.0-0",
+  "version": "9.1.0-2",
   "description": "Test utilities for marked and marked extensions",
   "main": "src/index.js",
   "type": "module",

package/src/get-tests.js

@@ -1,33 +1,43 @@
 import { loadTests } from "./load-tests.js";
 import { resolvePath } from "./helpers.js";
 
+/**
+ * Get tests from a directory or file
+ * @param {string | string[]} dirs Can be a string or an array of strings
+ * @returns {Tests | Tests[]} The return type will match the input, a tests object or an array of tests objects
+ */
 export async function getTests(dirs) {
-  if (typeof dirs === "string") {
-    return await loadTests(dirs);
-  }
-
   if (Array.isArray(dirs)) {
     return await Promise.all(dirs.map((dir) => loadTests(dir)));
   }
 
-  const keys = Object.keys(dirs);
-  const tests = await Promise.all(keys.map((key) => loadTests(dirs[key])));
-  const testsObj = {};
-  for (let i = 0; i < keys.length; i++) {
-    testsObj[keys[i]] = tests[i];
-  }
-
-  return testsObj;
+  return await loadTests(dirs);
 }
 
+/**
+ * Get all marked tests
+ * @returns {{
+ *   CommonMark: Tests,
+ *   GFM: Tests,
+ *   New: Tests,
+ *   Original: Tests,
+ *   ReDOS: Tests,
+ * }} All marked spec tests
+ */
 export async function getAllMarkedSpecTests() {
-  return await getTests({
-    CommonMark: resolvePath(
-      "../node_modules/marked-repo/test/specs/commonmark",
-    ),
-    GFM: resolvePath("../node_modules/marked-repo/test/specs/gfm"),
-    New: resolvePath("../node_modules/marked-repo/test/specs/new"),
-    Original: resolvePath("../node_modules/marked-repo/test/specs/original"),
-    ReDOS: resolvePath("../node_modules/marked-repo/test/specs/redos"),
-  });
+  const tests = await getTests([
+    resolvePath("../node_modules/marked-repo/test/specs/commonmark"),
+    resolvePath("../node_modules/marked-repo/test/specs/gfm"),
+    resolvePath("../node_modules/marked-repo/test/specs/new"),
+    resolvePath("../node_modules/marked-repo/test/specs/original"),
+    resolvePath("../node_modules/marked-repo/test/specs/redos"),
+  ]);
+
+  return {
+    CommonMark: tests[0],
+    GFM: tests[1],
+    New: tests[2],
+    Original: tests[3],
+    ReDOS: tests[4],
+  };
 }

package/src/html-differ.js

@@ -5,7 +5,26 @@ const htmlDiffer = new HtmlDiffer({
   ignoreComments: false,
 });
 
-export const htmlIsEqual = htmlDiffer.isEqual.bind(htmlDiffer);
+/**
+ * Check if html will display the same
+ * @param {string} actual The actual HTML
+ * @param {string} expected The expected HTML
+ * @returns {boolean} HTML is the same
+ */
+export function htmlIsEqual(actual, expected) {
+  return htmlDiffer.isEqual(actual, expected);
+}
+
+/**
+ * Get the first difference between actual and expected HTML
+ * @param {string} actual The actual HTML
+ * @param {string} expected The expected HTML
+ * @param {number} padding The number of characters to show around the first difference
+ * @returns {{
+ *   actual: string,
+ *   expected: string,
+ * }} An object with the characters around the index of the first difference in the expected and actual strings
+ */
 export async function firstDiff(actual, expected, padding) {
   padding = padding || 30;
   const diffHtml = await htmlDiffer.diffHtml(actual, expected);

package/src/output-table.js

@@ -1,3 +1,8 @@
+/**
+ * Display a table in stdout that lists the sections and what percentage of the tests are not marked shouldFail
+ * @param {string} title The title to display above the table
+ * @param {Tests} tests The tests to display a table for
+ */
 export function outputCompletionTable(title, tests) {
   let longestName = 0;
   let maxTests = 0;

package/src/run-tests.js

@@ -5,6 +5,17 @@ import assert from "node:assert";
 import { Marked } from "marked";
 import { outputCompletionTable } from "./output-table.js";
 
+/**
+ * Run spec tests
+ * @param {{
+ *   tests: Tests
+ *   defaultMarkedOptions: MarkedOptions,
+ *   parse: (marked: Marked, options: MarkedOptions, addExtension: (marked: Marked) => void) => string,
+ *   addExtension: (marked: Marked) => void,
+ *   isEqual: (actual: string, expected: string) => boolean,
+ *   diff: (actual: string, expected: string, padding: number) => {firstDiff: number, actual: string, expected: string},
+ * }} options
+ */
 export async function runTests({
   tests = {},
   defaultMarkedOptions = {},
@@ -71,6 +82,13 @@ export async function runTests({
   }
 }
 
+/**
+ * Run all marked specs with an added extension and optionally output completion table
+ * @param {{
+ *   addExtension: (marked: Marked) => void,
+ *   outputCompletionTable: boolean,
+ * }} options
+ */
 export async function runAllMarkedSpecTests({
   addExtension = () => {},
   outputCompletionTables = true,

package/test/get-tests.test.js

@@ -19,12 +19,4 @@ test("get-tests", async (t) => {
 
     assert.ok(tests[0].Tabs);
   });
-
-  await t.test("getTests(obj)", async () => {
-    const tests = await getTests({
-      test: resolvePath("../node_modules/marked-repo/test/specs/commonmark"),
-    });
-
-    assert.ok(tests.test.Tabs);
-  });
 });

package/types/index.d.ts

@@ -0,0 +1,18 @@
+import type { MarkedOptions } from "marked";
+
+export interface Spec {
+  section?: string;
+  markdown: string;
+  html: string;
+  example?: number;
+  options?: MarkedOptions;
+  only?: boolean;
+  skip?: boolean;
+  shouldFail?: boolean;
+}
+
+export interface Tests {
+  total: number;
+  pass: number;
+  specs: Spec[];
+}