update docs and types

README.md

@@ -1,3 +1,96 @@
 # @markedjs/testutils
 
 Test utilities for marked and marked extensions
+
+## API
+
+### `getAllMarkedSpecTests()`
+
+Get all marked [Tests](#tests)
+
+### `getTests(dirs)`
+
+Get [Tests](#tests) from a directory or file.
+`dirs` can be a string, an array of strings, or an object with string values.
+The return type is the same as the input a Tests object, an array of Tests objects, or an object with Tests object values.
+
+### `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 };
+```

src/get-tests.js

@@ -1,6 +1,11 @@
 import { loadTests } from "./load-tests.js";
 import { resolvePath } from "./helpers.js";
 
+/**
+ * Get tests from a directory or file
+ * @param {string | [string] | {key: string}} dirs Can be a string, array of strings, or an object with string values
+ * @returns {Tests | [Tests] | {key: Tests}} The return type will match the input, a tests object, array of tests objects, or an object with tests objects values
+ */
 export async function getTests(dirs) {
   if (typeof dirs === "string") {
     return await loadTests(dirs);
@@ -20,6 +25,16 @@ export async function getTests(dirs) {
   return testsObj;
 }
 
+/**
+ * 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(

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);

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;

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,

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[];
+}