{"id":13769371,"url":"https://github.com/tsdoc-test-reporter/reporter","last_synced_at":"2025-05-11T02:32:13.848Z","repository":{"id":199026569,"uuid":"624991481","full_name":"tsdoc-test-reporter/reporter","owner":"tsdoc-test-reporter","description":"TSDoc Test Reporter is a test reporter that attaches TSDoc comments to your test results. It enables you to attach metadata to your unit tests in the form of comments.","archived":false,"fork":false,"pushed_at":"2024-09-01T09:14:21.000Z","size":1266,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-17T05:32:43.150Z","etag":null,"topics":["jest","jest-reporter","jsdoc","jsdocs","test-automation","test-reporting","testing-tools","tsdoc","tsdocs","typescript","vitest","vitest-reporter"],"latest_commit_sha":null,"homepage":"https://tsdoc-test-reporter.github.io/reporter/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsdoc-test-reporter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2023-04-07T19:23:28.000Z","updated_at":"2024-09-01T09:14:24.000Z","dependencies_parsed_at":"2024-01-12T10:25:28.018Z","dependency_job_id":"ff434332-3b3b-429a-964f-12fe52a37244","html_url":"https://github.com/tsdoc-test-reporter/reporter","commit_stats":null,"previous_names":["tsdoc-test-reporter/reporter"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsdoc-test-reporter%2Freporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsdoc-test-reporter%2Freporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsdoc-test-reporter%2Freporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsdoc-test-reporter%2Freporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsdoc-test-reporter","download_url":"https://codeload.github.com/tsdoc-test-reporter/reporter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253507102,"owners_count":21919151,"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":["jest","jest-reporter","jsdoc","jsdocs","test-automation","test-reporting","testing-tools","tsdoc","tsdocs","typescript","vitest","vitest-reporter"],"created_at":"2024-08-03T17:00:23.069Z","updated_at":"2025-05-11T02:32:13.421Z","avatar_url":"https://github.com/tsdoc-test-reporter.png","language":"TypeScript","funding_links":[],"categories":["Packages"],"sub_categories":["Reporters"],"readme":"![social_preview](https://github.com/tsdoc-test-reporter/reporter/assets/21122051/5c8bb5cd-5772-47d2-8264-cc43cf5886ca)\n\n# @tsdoc-test-reporter\n\n**@tsdoc-test-reporter** is a test reporter that attaches [TSDoc](https://tsdoc.org/) comments to your test results. It enables you to attach metadata to your unit tests in the form of comments.\n\n## Output\n\n**[Example output from the reporter](https://tsdoc-test-reporter.github.io/kitchen-sink/)**\n\n## Features\n\n- Supports: **Jest** and **Vitest**\n- Parses _JSDoc_ and extended _TSDoc_ tags\n- Outputs: **JSON** or **HTML**\n- Extensive configuration of HTML report ([See UIOptions](https://tsdoc-test-reporter.github.io/reporter/types/core_src.UIOptions.html))\n- Displays error details\n- Supports using custom Tag Definitions\n- Works with regular JavaScript files as well\n- Works as a regular HTML/JSON reporter if you don't have any JSDoc\n- [See limitations](#limitations) on a list of what are some known limitations\n\n## Installing\n\n### Jest\n\n```bash\nnpm install @tsdoc-test-reporter/jest\n```\n\n### Vitest\n\n```bash\nnpm install @tsdoc-test-reporter/vitest\n```\n\n## Usage\n\n### Basic\n\n#### Jest\n\n1. Add reporter to your jest config (`jest.config.js`)\n\n```js\n/** @type {import('@jest/types').Config.InitialOptions} */\nmodule.exports = {\n\treporters: ['default', '@tsdoc-test-reporter/jest'],\n};\n```\n\n2. Add TSDoc comments to a test of your choice:\n\n```ts\n/**\n * @remarks\n * WCAG Criteria\n */\ntest('get correct background color based on text color', () =\u003e {\n\texpect(true).toBe(true);\n});\n```\n\n3. Run tests\n4. Open the newly generated file `tsdoc-test-reporter-report.html` in the browser of your choice\n\n#### Vitest\n\n1. Add reporter to config (`vite.config.ts`)\n\n```ts\n/// \u003creference types=\"vitest\" /\u003e\nimport { defineConfig } from 'vite';\n\nexport default defineConfig({\n\ttest: {\n\t\treporters: ['@tsdoc-test-reporter/vitest'],\n\t},\n});\n```\n\n2. Add TSDoc comments to a test of your choice:\n\n```ts\n/**\n * @remarks\n * WCAG Criteria\n */\ntest('get correct background color based on text color', () =\u003e {\n\texpect(true).toBe(true);\n});\n```\n\n3. Run tests (`vitest run`)\n4. Open the newly generated file `tsdoc-test-reporter-report.html` in the browser of your choice\n\n### With config\n\n#### Jest\n\n\u003e See [the documentation for the config](https://tsdoc-test-reporter.github.io/reporter/types/core_src.TsDocTestReporterConfig.html) for full docs of possible options\n\n```js\n/** @type {import('@tsdoc-test-reporter/jest').TsDocTestReporterConfig} */\nconst options = {\n\toutputFileName: 'reports/tsdoc-report',\n\tuiOptions: {\n\t\thtmlTitle: 'Title of HTML Page',\n\t},\n};\n\n/** @type {import('@jest/types').Config.InitialOptions} */\nmodule.exports = {\n\treporters: ['default', ['@tsdoc-test-reporter/jest', options]],\n};\n```\n\n#### Vitest\n\n\u003e See [the documentation for the config](https://tsdoc-test-reporter.github.io/reporter/types/core_src.TsDocTestReporterConfig.html) for full docs of possible options\n\n1. Create a file for the custom reporter in your project. Vitest does not allow passing config directly when specifying reporters so we need to call the reporter from our own custom reporter.\n\n```ts\n// reporter.ts\nimport TSDocTestReporter from '@tsdoc-test-reporter/vitest';\nimport { Reporter } from 'vitest/reporters';\nimport type { File, Vitest } from 'vitest';\n\nexport default class MyDefaultReporter extends Reporter {\n\tprivate reporter: TSDocTestReporter;\n\tconstructor() {\n\t\tthis.reporter = new TSDocTestReporter({\n\t\t\toutputFileName: 'reports/tsdoc-report',\n\t\t\tuiOptions: {\n\t\t\t\thtmlTitle: 'Title of HTML Page',\n\t\t\t},\n\t\t});\n\t}\n\tonInit(ctx: Vitest) {\n\t\tthis.reporter.onInit(ctx);\n\t}\n\tonFinished(files: File[]) {\n\t\tthis.reporter.onFinished(files);\n\t}\n}\n```\n\n2. Link reporter:\n\n```ts\n/// \u003creference types=\"vitest\" /\u003e\nimport { defineConfig } from 'vite';\n\nexport default defineConfig({\n\ttest: {\n\t\treporters: ['./reporter.ts'],\n\t},\n});\n```\n\n### With Custom User Supplied tags\n\n#### Jest\n\n```js\n/** @type {import('@tsdoc-test-reporter/jest').TsDocTestReporterConfig} */\nconst options = {\n\tcustomTags: [\n\t\t{\n\t\t\ttagName: '@customModifierTag',\n\t\t\tsyntaxKind: 2,\n\t\t},\n\t],\n};\n\n/** @type {import('@jest/types').Config.InitialOptions} */\nmodule.exports = {\n\treporters: ['default', ['@tsdoc-test-reporter/jest', options]],\n};\n```\n\n#### Vitest\n\n```ts\n// reporter.ts\nimport TSDocTestReporter from '@tsdoc-test-reporter/vitest';\nimport { Reporter } from 'vitest/reporters';\nimport type { File, Vitest } from 'vitest';\n\nexport default class MyDefaultReporter extends Reporter {\n\tprivate reporter: TSDocTestReporter;\n\n\tconstructor() {\n\t\tthis.reporter = new TSDocTestReporter({\n\t\t\tcustomTags: [\n\t\t\t\t{\n\t\t\t\t\ttagName: '@customModifierTag',\n\t\t\t\t\tsyntaxKind: 2,\n\t\t\t\t},\n\t\t\t],\n\t\t});\n\t}\n\tonInit(ctx: Vitest) {\n\t\tthis.reporter.onInit(ctx);\n\t}\n\tonFinished(files: File[]) {\n\t\tthis.reporter.onFinished(files);\n\t}\n}\n```\n\n## Limitations\n\n- Does not parse more than regular text in block comments as of writing. This is being worked on. You can create multiple tags when using a block tag. See example below. If you want a custom tagseparator that is not `,` you can supply it as an option.\n\n```ts\n/**\n * @remarks\n * unit,acceptance,whatever\n */\ntest('get correct background color based on text color', () =\u003e {\n\texpect(true).toBe(true);\n});\n```\n\n- Has limited support of inline tags. As of writing the supported case is using `@see {@link variableName}`. If the linked reference is a variable it will be resolved to a value if it is in scope of the source file (in the source file or imported by the source file). This is limited to string literals and object properties that are string literals (or enums). The example below works, and works if the enum is imported as a named import.\n\n```ts\nconst enum MyEnum {\n\tKey = 'Value',\n}\n\n/**\n * @see {@link MyEnum.Key}\n */\ntest('get correct background color based on text color', () =\u003e {\n\texpect(true).toBe(true);\n});\n```\n\n- Can not parse test titles that has parameters. If you are using `test.each` or similar where you are using placeholders in the test title, this test will not be able to match the JSDoc to the test assertion. You will have to wrap that each block with a `describe` and add a JSDoc to the `describe` block. If you are not using parameters in the title, `test.each` will work.\n\n```ts\n/**\n * @remarks\n * unit,acceptance\n */\ntest.each([{ name: 'value' }])('this will fail: $name', () =\u003e {\n\texpect(true).toBe(true);\n});\n```\n\n## How to contribute\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) on how to contribute and how to setup the project locally.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsdoc-test-reporter%2Freporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsdoc-test-reporter%2Freporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsdoc-test-reporter%2Freporter/lists"}