{"id":13727454,"url":"https://github.com/ikatyang/dts-jest","last_synced_at":"2025-04-07T11:04:15.332Z","repository":{"id":20871399,"uuid":"91051508","full_name":"ikatyang/dts-jest","owner":"ikatyang","description":"A preprocessor for Jest to snapshot test TypeScript declaration (.d.ts) files","archived":false,"fork":false,"pushed_at":"2024-02-25T04:59:43.000Z","size":1090,"stargazers_count":122,"open_issues_count":5,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-29T09:23:53.202Z","etag":null,"topics":["jest","jest-transform","test","typescript","typescript-definitions"],"latest_commit_sha":null,"homepage":"","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/ikatyang.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2017-05-12T04:31:10.000Z","updated_at":"2024-06-25T18:02:53.000Z","dependencies_parsed_at":"2024-01-10T20:10:56.856Z","dependency_job_id":"a4f64a50-de57-4c77-b1cf-6865972dc832","html_url":"https://github.com/ikatyang/dts-jest","commit_stats":{"total_commits":419,"total_committers":8,"mean_commits":52.375,"dds":0.6181384248210025,"last_synced_commit":"991667ce7bd5ae5383c4f998b73a65e2ced2436a"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikatyang%2Fdts-jest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikatyang%2Fdts-jest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikatyang%2Fdts-jest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikatyang%2Fdts-jest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ikatyang","download_url":"https://codeload.github.com/ikatyang/dts-jest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640461,"owners_count":20971557,"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-transform","test","typescript","typescript-definitions"],"created_at":"2024-08-03T01:03:57.463Z","updated_at":"2025-04-07T11:04:15.299Z","avatar_url":"https://github.com/ikatyang.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# dts-jest\n\n[![npm](https://img.shields.io/npm/v/dts-jest.svg)](https://www.npmjs.com/package/dts-jest)\n[![build](https://img.shields.io/travis/ikatyang/dts-jest/master.svg)](https://travis-ci.org/ikatyang/dts-jest/builds)\n[![coverage](https://img.shields.io/codecov/c/github/ikatyang/dts-jest.svg)](https://codecov.io/gh/ikatyang/dts-jest)\n\nA preprocessor for [Jest](https://facebook.github.io/jest/) to snapshot test [TypeScript declaration (.d.ts)](http://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html) files\n\n[Changelog](https://github.com/ikatyang/dts-jest/blob/master/CHANGELOG.md)\n\n- [Install](#install)\n- [Usage](#usage)\n- [Writing Tests](#writing-tests)\n- [Patterns](#patterns)\n  - [Patterns for Testing](#patterns-for-testing)\n  - [Patterns for Grouping](#patterns-for-grouping)\n  - [Patterns for File-Level Config](#patterns-for-file-level-config)\n- [Testing](#testing)\n- [Configs](#configs)\n- [Generate diff-friendly snapshots](#generate-diff-friendly-snapshots)\n- [Reporter](#reporter)\n- [FAQ](#faq)\n- [Development](#development)\n- [Related](#related)\n- [License](#license)\n\n## Install\n\n```sh\n# using npm\nnpm install --save-dev dts-jest jest typescript\n\n# using yarn\nyarn add --dev dts-jest jest typescript\n```\n\n- require `jest@\u003e=28` and `typescript@\u003e=4`\n\n  | dts-jest | jest     | typescript |\n  | -------- | -------- | ---------- |\n  | 26       | \u003e=28     | \u003e=4        |\n  | 25       | \u003e=28 \u003c30 | \u003e=2.3 \u003c5   |\n  | 24       | 27       | \u003e=2.3 \u003c5   |\n  | 23       | \u003e=22 \u003c27 | \u003e=2.3 \u003c5   |\n\n## Usage\n\nModify your [Jest config](https://facebook.github.io/jest/docs/en/configuration.html) so that looks something like:\n\n(./package.json)\n\n```json\n{\n  \"scripts\": {\n    \"test\": \"jest\"\n  },\n  \"jest\": {\n    \"moduleFileExtensions\": [\"ts\", \"js\", \"json\"],\n    \"testRegex\": \"/dts-jest/.+\\\\.ts$\",\n    \"transform\": {\"/dts-jest/.+\\\\.ts$\": \"dts-jest/transform\"}\n  }\n}\n```\n\nThis setup allow you to test files `**/dts-jest/**/*.ts` via `dts-jest`.\n\n## Writing Tests\n\nThe test cases must start with a comment `@dts-jest`, and the next line should be an expression that you want to test its type or value.\n\n(./dts-jest/example.ts)\n\n```ts\n// @dts-jest:pass:snap\nMath.max(1);\n\n// @dts-jest:pass\nMath.min(1, 2, 3); //=\u003e 1\n\n// @dts-jest:fail:snap\nMath.max('123');\n\n// @ts-expect-error:snap\nMath.max('123');\n```\n\n## Patterns\n\n### Patterns for Testing\n\n```ts\n// @dts-jest[flags] [description]\nexpression //=\u003e expected\n\n// @ts-expect-error[flags] [description]\nexpression //=\u003e expected\n```\n\n_Note:_ [`@ts-expect-error`](https://devblogs.microsoft.com/typescript/announcing-typescript-3-9-beta/#ts-expect-error-comments) is treated as an alias of `@dts-jest:fail` in `dts-jest`.\n\n- description\n  - optional\n  - default: `expression`\n- flag\n  - optional\n  - for test\n    - default: [`test`](https://facebook.github.io/jest/docs/en/api.html#testname-fn)\n    - `:only`: [`test.only`](https://facebook.github.io/jest/docs/en/api.html#testonlyname-fn)\n    - `:skip`: [`test.skip`](https://facebook.github.io/jest/docs/en/api.html#testskipname-fn)\n  - for type assertion\n    - default: none\n    - `:show`: `console.log(type)`\n    - `:pass`: `expect(() =\u003e type)`[`.not`](https://facebook.github.io/jest/docs/en/expect.html#not)[`.toThrow()`](https://facebook.github.io/jest/docs/en/expect.html#tothrowerror)\n    - `:fail`: `expect(() =\u003e type)`[`.toThrow()`](https://facebook.github.io/jest/docs/en/expect.html#tothrowerror)\n    - `:snap`:\n      - snapshot inferred type or diagnostic message\n      - `expect(type)`[`.toMatchSnapshot()`](https://facebook.github.io/jest/docs/en/expect.html#tomatchsnapshotoptionalstring)\n      - `expect(type)`[`.toThrowErrorMatchingSnapshot()`](https://facebook.github.io/jest/docs/en/expect.html#tothrowerrormatchingsnapshot)\n    - `:not-any`: `expect(type)`[`.not`](https://facebook.github.io/jest/docs/en/expect.html#not)[`.toBe(\"any\")`](https://facebook.github.io/jest/docs/en/expect.html#tobevalue)\n- expected\n  - optional\n  - `//=\u003e expected` or `/*=\u003e expected */`\n  - for value assertion\n    - default: none\n    - `?`: `console.log(value)`\n    - `:error`: `expect(() =\u003e value)`[`.toThrow()`](https://facebook.github.io/jest/docs/en/expect.html#tothrowerror)\n    - `:no-error`: `expect(() =\u003e value)`[`.not`](https://facebook.github.io/jest/docs/en/expect.html#not)[`.toThrow()`](https://facebook.github.io/jest/docs/en/expect.html#tothrowerror)\n    - others: `expect(value)`[`.toEqual(expected)`](https://facebook.github.io/jest/docs/en/expect.html#toequalvalue)\n\n### Patterns for Grouping\n\nTest cases after this pattern will be marked as that group.\n\n```ts\n// @dts-jest:group[flag] [description]\n```\n\nIf you need a block scope for your tests you can use a Block Statement.\n\n```ts\n// @dts-jest:group[flag] [description]\n{\n  // your tests\n}\n```\n\n- description\n  - default: `''`\n- flag\n  - default: [`describe`](https://facebook.github.io/jest/docs/en/api.html#describename-fn)\n  - `:only`: [`describe.only`](https://facebook.github.io/jest/docs/en/api.html#describeonlyname-fn)\n  - `:skip`: [`describe.skip`](https://facebook.github.io/jest/docs/en/api.html#describeskipname-fn)\n\n### Patterns for File-Level Config\n\nFile-level config uses the first comment to set, only docblock will be detected.\n\n```ts\n/** @dts-jest [action:option] ... */\n```\n\n- action:\n  - `enable`: set to `true`\n  - `disable`: set to `false`\n- option:\n  - `test-type`: `test_type` option in [configs](#configs)\n  - `test-value`: `test_value` option in [configs](#configs)\n\n## Testing\n\nIt's recommended you to run Jest in watching mode via `--watch` flag.\n\n```sh\nnpm run test -- --watch\n```\n\n**NOTE**: If you had changed the version of `dts-jest`, you might have to use `--no-cache` flag since Jest may use the older cache.\n\nAfter running the [example tests](#writing-tests) with `npm run test`, you'll get the following result:\n\n```text\n PASS  tests/example.ts\n  Math.max(1)\n    ✓ (type) should not throw error\n    ✓ (type) should match snapshot\n  Math.max('123')\n    ✓ (type) should throw error\n    ✓ (type) should match snapshot\n  Math.min(1, 2, 3)\n    ✓ (type) should not throw error\n\nSnapshot Summary\n › 2 snapshots written in 1 test suite.\n\nTest Suites: 1 passed, 1 total\nTests:       5 passed, 5 total\nSnapshots:   2 added, 2 total\nTime:        0.000s\nRan all test suites.\n```\n\nSince snapshot testing will always pass and write the result at the first time, it's reommended you to use `:show` flag to see the result first without writing results.\n\n(./dts-jest/example.ts)\n\n```ts\n// @dts-jest:pass:show\nMath.max(1);\n\n// @dts-jest:fail:show\nMath.max('123');\n\n// @dts-jest:pass\nMath.min(1, 2, 3); //=\u003e 1\n```\n\n```text\n PASS  dts-jest/example.ts\n  Math.max(1)\n    ✓ (type) should show report\n    ✓ (type) should not throw error\n  Math.max('123')\n    ✓ (type) should show report\n    ✓ (type) should throw error\n  Math.min(1, 2, 3)\n    ✓ (type) should not throw error\n\nTest Suites: 1 passed, 1 total\nTests:       5 passed, 5 total\nSnapshots:   0 total\nTime:        0.000s\nRan all test suites.\n\n  console.log dts-jest/example.ts:2\n\n    Inferred\n\n      Math.max(1)\n\n    to be\n\n      number\n\n  console.log dts-jest/example.ts:5\n\n    Inferring\n\n      Math.max('123')\n\n    but throw\n\n      Argument of type '\"123\"' is not assignable to parameter of type 'number'.\n```\n\n## Configs\n\nConfigs are in `_dts_jest_` field of Jest config `globals`.\n\nThere are several options\n\n- test_type\n  - default: `true`\n  - enable type testing\n  - [file-level config](#patterns-for-file-level-config) available\n- test_value\n  - default: `false`\n  - enable value testing\n  - [file-level config](#patterns-for-file-level-config) available\n- enclosing_declaration\n  - default: `false`\n  - unwrap type alias\n- typescript\n  - default: `typescript` (node resolution)\n  - specify which path of typescript to use\n  - `\u003ccwd\u003e` available\n- compiler_options\n  - default: `{}`\n  - specify which *path of `tsconfig.json` (string)* ~~or *compilerOptions (object)*~~ (deprecated, does not support `typeRoots` for _object_) to use\n- type_format_flags\n  - default: `ts.TypeFormatFlags.NoTruncation`\n  - specify type format\n- transpile\n  - default: `true`\n  - transpile code before testing, only affect tests that needs to test value\n  - transpiling code will cause line number incorrect, it's better to disable this option if possible\n\nFor example:\n\n(./package.json)\n\n```json\n{\n  \"jest\": {\n    \"globals\": {\n      \"_dts_jest_\": {\n        \"compiler_options\": {\n          \"strict\": true,\n          \"target\": \"es6\"\n        }\n      }\n    }\n  }\n}\n```\n\n## Generate diff-friendly snapshots\n\nOriginally, snapshots and source content are in different files, it is hard to check their difference before/after, so here comes the `dts-jest-remap` for generating diff-friendly snapshots.\n\n(./tests/example.ts)\n\n```ts\n// @dts-jest:snap\nMath.max(1, 2, 3);\n```\n\n(./tests/`__snapshots__`/example.ts.snap) note this file is generated by Jest\n\n```ts\n// Jest Snapshot v1, https://goo.gl/fbAQLP\nexports[`Math.max(1, 2, 3) 1`] = `\"number\"`;\n```\n\nThis command will combine both snapshots and source content in one file:\n\n```sh\ndts-jest-remap ./tests/example.ts --outDir ./snapshots\n```\n\n(./snapshots/example.ts)\n\n```ts\n// @dts-jest:snap -\u003e number\nMath.max(1, 2, 3);\n```\n\n```text\nUsage: dts-jest-remap [--outDir \u003cpath\u003e] [--rename \u003ctemplate\u003e] \u003cTestFileGlob\u003e ...\n\nOptions:\n  --check, -c          Throw error if target content is different from output\n                       content                                         [boolean]\n  --help, -h           Show help                                       [boolean]\n  --listDifferent, -l  Print the filenames of files that their target content is\n                       different from output content                   [boolean]\n  --outDir, -o         Redirect output structure to the directory       [string]\n  --rename, -r         Rename output filename using template {{variable}},\n                       available variable: filename, basename, extname  [string]\n  --typescript, -t     Specify which TypeScript source to use           [string]\n  --version, -v        Show version number                             [boolean]\n```\n\n## Reporter\n\nIf you'd like to know which typescript you are using, add `dts-jest/reporter` to your [Jest reporters](https://facebook.github.io/jest/docs/en/configuration.html#reporters-array-modulename-modulename-options), for example:\n\n```json\n{\n  \"reporters\": [\n    \"default\",\n    \"dts-jest/reporter\"\n  ]\n}\n```\n\nIt'll show the TS version and path after testing:\n\n```text\n[dts-jest] using TypeScript v0.0.0 from path/to/typescript\n```\n\n## FAQ\n\n- `Compiler option 'lib' requires a value of type list`\n  - Arrays in `jest` \u003e `globals` \u003e `_dts_jest_` will be transformed into objects.\n  - Consider to use [`setupFiles`](https://facebook.github.io/jest/docs/en/configuration.html#setupfiles-array) to set configs (`globals._dts_jest_ = { ... }`).\n  - See [jest#2093](https://github.com/facebook/jest/issues/2093) for details.\n- `Debug Failure`\n  - This is mostly caused by regex literal due to the printer bug [TypeScript#18071](https://github.com/Microsoft/TypeScript/issues/18071) (fixed in TS v2.6).\n  - Workaround: use regex instance instead, e.g. `new RegExp('something')`.\n\n## Development\n\n```sh\n# lint\nyarn run lint\n\n# test\nyarn run test\n\n# build\nyarn run build\n```\n\n## Related\n\n- [dtslint](https://github.com/Microsoft/dtslint): A utility built on TSLint for linting TypeScript declaration (.d.ts) files\n- [typings-checker](https://github.com/danvk/typings-checker): Positive and negative assertions about TypeScript types and errors\n\n## License\n\nMIT © [Ika](https://github.com/ikatyang)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikatyang%2Fdts-jest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fikatyang%2Fdts-jest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikatyang%2Fdts-jest/lists"}