{"id":15646325,"url":"https://github.com/azu/power-doctest","last_synced_at":"2025-04-06T12:07:34.064Z","repository":{"id":12215664,"uuid":"14822872","full_name":"azu/power-doctest","owner":"azu","description":"JavaScript Doctest for JavaScript, Markdown and Asciidoc.","archived":false,"fork":false,"pushed_at":"2025-03-02T08:37:01.000Z","size":1325,"stargazers_count":52,"open_issues_count":5,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T11:06:28.463Z","etag":null,"topics":["asciidoc","doctest","document","javascript","markdown","test","testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/azu.png","metadata":{"funding":{"github":"azu"},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-11-30T14:57:20.000Z","updated_at":"2025-03-02T23:21:47.000Z","dependencies_parsed_at":"2024-06-19T19:06:38.649Z","dependency_job_id":"3826f65b-385b-4478-9391-26ec7a7fd05c","html_url":"https://github.com/azu/power-doctest","commit_stats":{"total_commits":312,"total_committers":4,"mean_commits":78.0,"dds":"0.054487179487179516","last_synced_commit":"6aad1dc068a20350a5890a0a013a605c891edeea"},"previous_names":[],"tags_count":57,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Fpower-doctest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Fpower-doctest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Fpower-doctest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Fpower-doctest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/azu","download_url":"https://codeload.github.com/azu/power-doctest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247478318,"owners_count":20945266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asciidoc","doctest","document","javascript","markdown","test","testing"],"created_at":"2024-10-03T12:12:26.313Z","updated_at":"2025-04-06T12:07:34.044Z","avatar_url":"https://github.com/azu.png","language":"TypeScript","funding_links":["https://github.com/sponsors/azu"],"categories":[],"sub_categories":[],"readme":"# power-doctest [![Actions Status: test](https://github.com/azu/power-doctest/workflows/test/badge.svg)](https://github.com/azu/power-doctest/actions?query=workflow%3A\"test\")\n\nA monorepo for power-doctest.\n\npower-doctest is a project that provide doctest system for JavaScript.\n\n## Features\n\n- Run Comments as Assertions\n- Support JavaScript, Markdown Code Block, Asciidoctor Code Block\n- Control doctest behavior from comments \n\n## Packages\n\n- [comment-to-assert](./packages/comment-to-assert)\n    - `// =\u003e expression` to `assert`\n- [power-doctest](./packages/power-doctest)\n    - A command line tool for power-doctest\n    - Convert code and Run the code as doctest\n- [@power-doctest/core](packages/@power-doctest/core)\n    - Convert code to doctest-ready code\n- [@power-doctest/tester](./packages/@power-doctest/tester)\n    - A Test Runner for A power-doctest.\n- [@power-doctest/javascript](./packages/@power-doctest/javascript)\n    - A JavaScript parser for power-doctest.\n- [@power-doctest/markdown](./packages/@power-doctest/markdown)\n    - A Markdown parser for power-doctest.\n- [@power-doctest/asciidoctor](./packages/@power-doctest/asciidoctor)\n    - A Asciidoctor parser for power-doctest.\n\n## power-doctest\n\npower-doctest is consisted of two parts.\n\n- Comment Assertion Syntax\n- Doctest Control Annotation \n\n### Comment Assertion Syntax\n\nYou can write following comment in your JavaScript code.\nThese comment will be canistered to assertion.\n\n| Syntax                                            | Transformed                                                  |\n| ------------------------------------------------- | ------------------------------------------------------------ |\n| `1; // =\u003e 2`                                      | `assert.strictEqual(1, 2)`                                   |\n| `console.log(1); // =\u003e 2`                         | `assert.strictEqual(1, 2)`                                   |\n| `a; // =\u003e b`                                      | `assert.deepStrictEqual(a, b)`                                   |\n| `[1, 2, 3]; // =\u003e [3, 4, 5]`                      | `assert.deepStrictEqual([1, 2, 3], [3, 4, 5])`               |\n| `console.log({ a: 1 }): // =\u003e { b: 2 }`            | `assert.deepStrictEqual({ a: 1 }, { b: 2 })`                 |\n| `throw new Error(\"message\"); // =\u003e Error: \"message\"` | `assert.throws(function() {throw new Error(\"message\"); });\"` |\n| `Promise.resolve(1); // Resolve: 2`               | `Promise.resolve(Promise.resolve(1)).then(v =\u003e { assert.strictEqual(1, 2) }) ` |\n| `Promise.reject(1); // Reject: 2`                 | `assert.rejects(Promise.reject(1))`                          |\n\nFor more details, see [comment-to-assert](https://www.npmjs.com/package/comment-to-assert).\n\n### Doctest Control Annotation\n\nDoctest Control Annotation is defined in Language specific plugin.\nFor more details, see following package's README.\n\n- [@power-doctest/javascript](./packages/@power-doctest/javascript)\n    - A JavaScript parser for power-doctest.\n- [@power-doctest/markdown](./packages/@power-doctest/markdown)\n    - A Markdown parser for power-doctest.\n- [@power-doctest/asciidoctor](./packages/@power-doctest/asciidoctor)\n    - A Asciidoctor parser for power-doctest.\n\n## Recipes\n\n### Doctest JavaScript Code\n\nUse [@power-doctest/tester](./packages/@power-doctest/tester) and [@power-doctest/javascript](./packages/@power-doctest/javascript) in [Mocha](https://mochajs.org/).\n\n```js\nimport { test } from \"@power-doctest/tester\";\nimport { parse } from \"@power-doctest/javascript\";\nconst globby = require(\"globby\");\nconst fs = require(\"fs\");\nconst path = require(\"path\");\n// doctest for source/**/*.js\ndescribe(\"doctest:js\", function() {\n    const sourceDir = path.join(__dirname, \"..\", \"source\");\n    const files = globby.sync([\n        `${sourceDir}/**/*.js`,\n        `!${sourceDir}/**/node_modules{,/**}`\n    ]);\n    files.forEach(filePath =\u003e {\n        const normalizeFilePath = filePath.replace(sourceDir, \"\");\n        it(`doctest:js ${normalizeFilePath}`, function() {\n            const content = fs.readFileSync(filePath, \"utf-8\");\n            const parsedResults = parse({\n                content,\n                filePath\n            });\n            const parsedCode = parsedResults[0];\n            return test(parsedCode).catch(error =\u003e {\n                // Stack Trace like\n                console.error(`StrictEvalError: strict eval is failed\n    at strictEval (${filePath}:1:1)`);\n                return Promise.reject(error);\n            });\n        });\n    });\n});\n```\n\n**Example**\n\n- \u003chttps://github.com/asciidwango/js-primer/blob/master/test/example-test.js\u003e\n\n### Doctest JavaScript Code in Markdown\n\nUse [@power-doctest/tester](./packages/@power-doctest/tester) and [@power-doctest/markdown](./packages/@power-doctest/markdown) in [Mocha](https://mochajs.org/).\n\n```js\nimport { test } from \"@power-doctest/tester\";\nimport { parse } from \"@power-doctest/markdown\";\nconst globby = require(\"globby\");\nconst fs = require(\"fs\");\nconst path = require(\"path\");\nconst transform = (code) =\u003e {\n    return code; // you need pre transform for the code if needed.\n};\n// doctest for source/**/*.md\ndescribe(\"doctest:md\", function() {\n    const sourceDir = path.join(__dirname, \"..\", \"source\");\n    const files = globby.sync([\n        `${sourceDir}/**/*.md`,\n        `!${sourceDir}/**/node_modules{,/**}`,\n    ]);\n    files.forEach(filePath =\u003e {\n        const normalizeFilePath = filePath.replace(sourceDir, \"\");\n        describe(`${normalizeFilePath}`, function() {\n            const content = fs.readFileSync(filePath, \"utf-8\");\n            const parsedCodes = parse({\n                filePath,\n                content\n            });\n            // try to eval\n            const dirName = path.dirname(filePath).split(path.sep).pop();\n            parsedCodes.forEach((parsedCode, index) =\u003e {\n                const codeValue = parsedCode.code;\n                const testCaseName = codeValue.slice(0, 32).replace(/[\\r\\n]/g, \"_\");\n                it(dirName + \": \" + testCaseName, function() {\n                    return test({\n                        ...parsedCode,\n                        code: transform(parsedCode.code)\n                    }, {\n                        defaultDoctestRunnerOptions: {\n                            // Default timeout: 2sec\n                            timeout: 1000 * 2\n                        }\n                    }).catch(error =\u003e {\n                        const filePathLineColumn = `${error.fileName}:${error.lineNumber}:${error.columnNumber}`;\n                        console.error(`Markdown Doctest is failed\n  at ${filePathLineColumn}\n\n----------\n${codeValue}\n----------\n`);\n                        return Promise.reject(error);\n                    });\n                });\n            });\n        });\n    });\n});\n```\n\n**Example**\n\n- \u003chttps://github.com/asciidwango/js-primer/blob/master/test/markdown-doc-test.js\u003e\n\n### Doctest JavaScript in Asciidoctor\n\nUse [@power-doctest/tester](./packages/@power-doctest/tester) and [@power-doctest/asciidoctor](./packages/@power-doctest/asciidoctor) in [Mocha](https://mochajs.org/).\n\n```js\nconst { test } = require(\"@power-doctest/tester\");\nconst { parse } = require(\"@power-doctest/asciidoctor\");\nconst globby = require(\"globby\");\nconst fs = require(\"fs\");\nconst path = require(\"path\");\n// Avoid \"do not support nested sections\" Error\n// Replace Header with Dummy text\nconst replaceDummyHeader = (content) =\u003e {\n    return content.split(\"\\n\").map(line =\u003e {\n        return line.replace(/^(=+)/g, (all, match) =\u003e {\n            return \"♪\".repeat(match.length);\n        });\n    }).join(\"\\n\");\n};\n// doctest for source/**/*.adoc\ndescribe(\"doctest:adoc\", function () {\n    const sourceDir = path.join(__dirname, \"..\", \"source\");\n    const files = globby.sync([\n        `${sourceDir}/**/*.adoc`,\n        `!**/node_modules{,/**}`,\n    ]);\n    files.forEach(filePath =\u003e {\n        const normalizeFilePath = filePath.replace(sourceDir, \"\");\n        describe(`${normalizeFilePath}`, function () {\n            const content = fs.readFileSync(filePath, \"utf-8\");\n            const parsedCodes = parse({\n                filePath,\n                content: replaceDummyHeader(content)\n            });\n            console.log(\"parsedCodes\", parsedCodes);\n            // try to eval\n            const dirName = path.dirname(filePath).split(path.sep).pop();\n            parsedCodes.forEach((parsedCode, index) =\u003e {\n                const codeValue = parsedCode.code;\n                const testCaseName = codeValue.slice(0, 32).replace(/[\\r\\n]/g, \"_\");\n                it(dirName + \": \" + testCaseName, function () {\n                    return test(parsedCode).catch(error =\u003e {\n                        const filePathLineColumn = `${error.fileName}:${error.lineNumber}:${error.columnNumber}`;\n                        console.error(`Asciidoc Doctest is failed\n  at ${filePathLineColumn}\n\n----------\n${codeValue}\n----------\n`);\n                        return Promise.reject(error);\n                    });\n                });\n            });\n        });\n    });\n});\n```\n\n**Example**\n\n- \u003chttps://github.com/azu/promises-book/blob/7db237e6274a3af8db3b5cb92a2dd8574d9890e5/test/doctest.js\u003e\n\n## Development\n\nRequire [pnpm](https://pnpm.io/)\n \nInstall project\n\n    pnpm install\n    pnpm boostrap\n\nBuild\n\n    pnpm run build\n\nTest\n\n    pnpm test\n    \nRelease: use npm\n\n    npm run versionup\n    # GH_TOKEN=\"${GITHUB_TOKEN}\" npm run versionup:patch --create-release=github\n    # prepare release note\n    npm relase\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazu%2Fpower-doctest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazu%2Fpower-doctest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazu%2Fpower-doctest/lists"}