2b:null 2c:["$","title",null,{"children":"Reactive Unit Testing and Reporting Framework | Tom Larkworthy | Observable"}] 31:T63b,md`# Reactive Unit Testing and Reporting Framework

A test suite that updates as you fix bugs in realtime. Combines with [healthcheck](https://observablehq.com/@endpointservices/healthcheck) to create a CI. - Monitorable with [healthcheck](https://observablehq.com/@endpointservices/healthcheck) - Followable stack track from failure to implementation - filter tests by __regex__ - rerun tests by pressing enter. - Familiar Jest expressions Only matched tests are run, allowing you to focus on executing individual tests precisely. Import the suite ~~~js import {createSuite, expect} from '@tomlarkworthy/testing' ~~~ Create the UI ~~~js viewof suite = createSuite({ name: "mySuite", timeout_ms: 1000 }) ~~~ Create named tests using [jest expect](https://jestjs.io/docs/en/expect). ~~~js suite.test("A passing test", () => {expect(true).toBe(true)}) ~~~ See the [example here](https://observablehq.com/@tomlarkworthy/testing-example). ### Change log - 2024-04-18 Added listenability with suite.viewofResults - 2021-11-10 Remove TAP link, [healthcheck](https://observablehq.com/@endpointservices/healthcheck) is better. - 2020-03-23 TAP reports are now hosted by "orchestrator" cells so can be used to test serverless cell services - 2020-02-14 Collaberation between [@chonghorizons](https://observablehq.com/@chonghorizons) and [@tomlarkworthy](https://observablehq.com/@tomlarkworthy) to add *timeout_ms* and explicit _done_() callback `32:T112a,createSuite = ({ name = "tests", // Set to null to turn of tap report link timeout_ms = 30000 } = {}) => { const id = pseudouuid(); const tests = {}; const results = {}; const viewofResults = Inputs.input(results); var filter = ""; const regex = () => new RegExp(filter); function updateUI() { reconcile(document.getElementById(id), generate()); } // from https://spin.atomicobject.com/2020/01/16/timeout-promises-nodejs/ function promiseWithTimeout(timeoutMs, promise, failureMessage) { let timeoutHandle; const timeoutPromise = new Promise((resolve, reject) => { timeoutHandle = setTimeout( () => reject(new Error(failureMessage)), timeoutMs ); }); return Promise.race([promise, timeoutPromise]).then((result) => { clearTimeout(timeoutHandle); return result; }); } async function maybeRunTest(name) { if (regex().test(name)) { results[name] = undefined; updateUI(); try { await promiseWithTimeout(timeout_ms, tests[name](), "Timeout"); results[name] = "ok"; viewofResults.dispatchEvent(new Event("input", { bubbles: true })); updateUI(); return results[name]; } catch (err) { results[name] = err; viewofResults.dispatchEvent(new Event("input", { bubbles: true })); updateUI(); throw err; } } } function filterChange(evt) { if (filter !== evt.target.value) { filter = evt.target.value; updateUI(); } if (evt.keyCode === 13) { Object.keys(tests).map((label) => maybeRunTest(label)); } } function generate() { return html`

${name ? html`

${name}

` : null} e.stopPropagation()} onkeyup=${filterChange} value="${filter}" placeholder="test filter regex"> ${Object.keys(results) .filter((label) => regex().test(label)) .sort() .map( (label) => html.fragment` ` )}

name	value
${label}	${ results[label] ? (results[label] + "").slice(0, 200) : null }

`; } const api = { viewofResults: viewofResults, results: results, test: async (label, fn) => { // console.log(`Test scheduled: ${label}`); results[label] = undefined; const run = async () => { // If the user supplies a done handler in the fn, use that return fn.length == 1 ? new Promise(async (resolve, reject) => { const done = (error) => { if (error) reject(error); else resolve(); }; try { await fn(done); } catch (error) { reject(error); } }) : fn(); }; tests[label] = run; const result = await maybeRunTest(label); const color = result === "ok" ? "green" : "red"; return html`

${label}: ${result} goto suite

`; } }; { // Navigation widget const isLocalLink = (a) => a instanceof HTMLAnchorElement && a.getAttribute("href").match(/^#/); const scrollTo = (e) => { let l = e.target, t; if ( isLocalLink(l) && (t = document.querySelector(`[name="${l.hash.slice(1)}"]`)) ) { e.preventDefault(); t.scrollIntoView(); } }; document.addEventListener("click", scrollTo); invalidation.then(() => document.removeEventListener("click", scrollTo)); } const view = html`${generate()}`; view.value = api; return view; }33:T42f,function report(suite, { timeout = 10000 } = {}) { function tap(suite) { // Ugly indentation here to avoid whitespace in the TAP report. return `TAP version 13 1..${Object.keys(suite.results).length} ${Object.keys(suite.results) .sort() .map((name, index) => { let status = "not ok"; let details = ""; if (suite.results[name] === "ok") status = "ok"; if (status === "not ok") { details = `\n ---\n message: ${JSON.stringify( suite.results[name] ).slice(0, 1000)}`; } return `${status} ${index + 1} - ${name}${details}`; }) .join("\n")}`; } // This is a bit of a crappy poll loop // but its only intended for http handler use // https://stackoverflow.com/questions/30505960/use-promise-to-wait-until-polled-condition-is-satisfied return new Promise(function (resolve, reject) { function waitForResults() { if (!Object.values(suite.results).includes(undefined)) return resolve(tap(suite)); setTimeout(waitForResults, 100); } setTimeout(waitForResults, 1000); }); }34:[{"id":"b85565d2b6f001a2db39bdbeafbf5aa687188a77a6f65088a3da275743064af6ec763f97d4575207873165a49b07b65e492987b100b4a0d6bbe3df1f74efda1e","href":"https://static.observableusercontent.com/files/b85565d2b6f001a2db39bdbeafbf5aa687188a77a6f65088a3da275743064af6ec763f97d4575207873165a49b07b65e492987b100b4a0d6bbe3df1f74efda1e","name":"noun_test_2404407.svg","type":"image/svg+xml","lastModified":1605162986226.347,"size":2988}] 2f:{"id":"c7a3b20cec5d4dd9","slug":"testing","title":"Reactive Unit Testing and Reporting Framework","thumbnail":"30f21ae174a80bb829c64544cf5b5e218f1681a8534d7230d2a1d25a77c3c159","access_level":"public","create_time":"$D2020-11-10T22:13:11.627Z","update_time":"$D2026-09-08T20:06:33.874Z","view_time":null,"first_public_time":"$D2020-11-12T00:13:22.631Z","fork":false,"stars":20,"starred":false,"owner":{"type":"team","id":"7db5ed2b0697d645","login":"tomlarkworthy","name":"Tom Larkworthy","avatar_url":"https://avatars-next.observableusercontent.com/47327a8bc1966f2186dcb3ebf4b7ee6e4e7ab9a5c2a07405aff57200ea778f71","tier":"starter_2024"},"version":733,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"5215f6ec4a999d40","login":"tomlarkworthy","name":"Tom Larkworthy","avatar_url":"https://avatars-next.observableusercontent.com/47327a8bc1966f2186dcb3ebf4b7ee6e4e7ab9a5c2a07405aff57200ea778f71","tier":null}],"members":[{"type":"individual","id":"5215f6ec4a999d40","login":"tomlarkworthy","name":"Tom Larkworthy","avatar_url":"https://avatars-next.observableusercontent.com/47327a8bc1966f2186dcb3ebf4b7ee6e4e7ab9a5c2a07405aff57200ea778f71","tier":null,"role":"editor"}],"comments":[{"id":"a1b0de86e4a2010e","reply_to_id":null,"content":"> name = \"tests\", // Set to undefined to turn of tap report link\n\nIt should be: \n\n> name = \"tests\", // Set to null to turn of tap report link\n\nbecause if name is undefined, it will be set to the default value 'tests'","create_time":"$D2021-03-01T19:06:50.735Z","update_time":null,"resolved":true,"user":{"type":"individual","id":"bf1872cca880d345","login":"severo","name":"Sylvain Lesage","avatar_url":"https://avatars-next.observableusercontent.com/7713195c83e5bfd8090ffe70c871c23e743c711e9e712675c99a8960ca8c7944","tier":null}},{"id":"e4892adbee1a2c94","reply_to_id":"a1b0de86e4a2010e","content":"awesome thanks","create_time":"$D2021-03-01T19:28:31.855Z","update_time":null,"resolved":true,"user":{"type":"individual","id":"5215f6ec4a999d40","login":"tomlarkworthy","name":"Tom Larkworthy","avatar_url":"https://avatars-next.observableusercontent.com/47327a8bc1966f2186dcb3ebf4b7ee6e4e7ab9a5c2a07405aff57200ea778f71","tier":null}}],"custom_thumbnail":true,"trashed":false,"subscribed":null,"forks":9,"collection":{"id":"6a1548aef3fabff0","slug":"libraries","title":"libraries","owner":{"id":"7db5ed2b0697d645","login":"tomlarkworthy","name":"Tom Larkworthy"}},"type":"notebook","body":{"title":"Reactive Unit Testing and Reporting Framework","cells":[{"id":0,"value":"$31","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":629,"value":"md`## Lazy loading\n\nYou might not want testing to be a static dependancy, you can use something like the following to programatically load the testing library only if some condition is true. (thanks [@mootari](/@mootari) who donated this)\n~~~js\ntesting = {\n const [{ Runtime }, { default: define }] = await Promise.all([\n import(\n \"https://cdn.jsdelivr.net/npm/@observablehq/runtime@4/dist/runtime.js\"\n ),\n import(\\`https://api.observablehq.com/@tomlarkworthy/testing.js?v=3\\`)\n ]);\n const module = new Runtime().module(define);\n return Object.fromEntries(\n await Promise.all(\n [\"expect\", \"createSuite\"].map((n) => module.value(n).then((v) => [n, v]))\n )\n );\n}\n~~~\n\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":343,"value":"$32","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":405,"value":"$33","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":248,"value":"md`## Test Suite UI`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":15,"value":"viewof suite = createSuite({\n timeout_ms: 5000\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":561,"value":"md`#### The report links to an always on TAP report`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":554,"value":"html`

${await report(suite)}

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":220,"value":"md`## Some Tests`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":27,"value":"suite.test(\"sync pass\", () => expect(true).toBe(true))","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":500,"value":"md`#### Demo of what a failing test looks like`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":195,"value":"suite.test(\"sync fail\", () => expect(true).toBe(false))","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":75,"value":"suite.test(\"throw exception\", () => {\n console.log(\"Run: Throws exception\")\n expect(() => {\n throw new Error(\"Expected exception\");\n }).toThrow();\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":463,"value":"suite.test(\"asyncORIG - original function\", async () => {\n console.log(\"Run: async function\")\n await new Promise(resolve => setTimeout(resolve, 500));\n return \"foo2\"\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":462,"value":"md`### Some more async function tests\n\nadded by @chonghorizons, Feb2021`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":505,"value":"md`#### Demo of timeout`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":461,"value":"suite.test(\"async0 - should fail, no resolve\", async () => {\n console.log(\"Run: async function\")\n// await new Promise(resolve => setTimeout(resolve, 1000));\n await new Promise( resolve => {});\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":142,"value":"suite.test(\"async1 check returned data\", async () => {\n await new Promise(resolve => setTimeout(()=>resolve(\"foo\"), 1000))\n .then(data => {\n expect(data).toBe(\"foo\");\n })\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":459,"value":"md`#### Demo of not calling _done_ will timeout`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":458,"value":"suite.test(\"async2 function hanging example, should fail\", done => {\n \n});\n\n// based on \"unresolved\" example at https://jestjs.io/docs/en/asynchronous\n","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":547,"value":"md`#### Demo of _done_ param is propogated as an error`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":549,"value":"suite.test(\"done arg is an error\", done => {\n done(new Error(\"Not an error really\"));\n})\n\n// based on \"unresolved\" example at https://jestjs.io/docs/en/asynchronous","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":530,"value":"md`#### Demo of normal errors will fail a test with _done_`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":526,"value":"suite.test(\"Failure with done raises error\", async done => {\n expect(true).toBe(false);\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":456,"value":"suite.test(\"async4: the data is peanut butter\", () => {\n const fetchData = () => new Promise((resolve) => resolve(\"peanut butter\"));\n return fetchData().then((data) => {\n expect(data).toBe(\"peanut butter\");\n });\n})\n\n// adapted example from https://jestjs.io/docs/en/asynchronous\n// not using await","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":675,"value":"## Results are listenable","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":677,"value":"suite.viewofResults.value","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":666,"value":"html = htl.html","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":2,"value":"import { reconcile } from \"@tomlarkworthy/reconcile-nanomorph\"","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":648,"value":"pseudouuid = () => Math.random().toString(16).substring(3)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":185,"value":"expect = {\n // The bundle assigns window.expect. Loaded by