├── .editorconfig ├── .gitattributes ├── .github └── workflows │ └── test.yml ├── .gitignore ├── .npmignore ├── .prettierrc.js ├── CHANGELOG.md ├── LICENSE ├── README.md ├── bin └── dts-jest-remap.js ├── fixtures ├── create-assertion-expression │ └── example.ts ├── create-setup-expression │ └── example.ts ├── create-snapshots │ ├── example.ts │ ├── no-assertion.ts │ ├── ts-expect-error.ts │ └── unmatched.ts ├── find-docblock-options │ ├── disable-test-type.ts │ ├── disable-test-value.ts │ ├── enable-test-type.ts │ ├── enable-test-value.ts │ ├── multi-option-value.ts │ ├── normal-comment.ts │ ├── second-docblock.ts │ └── unexpected.ts ├── find-trigger-bodies │ ├── invalid-group.ts │ ├── simple.ts │ └── unattachable.ts ├── find-trigger-footers │ ├── simple.ts │ └── unattachable.ts ├── find-trigger-headers │ ├── group.ts │ ├── method.ts │ ├── simple.ts │ ├── ts-expect-error-equivalent.ts │ ├── ts-expect-error.ts │ └── unmatched.ts ├── find-triggers │ └── example.ts ├── load-compiler-options │ ├── example │ │ ├── placeholder.ts │ │ ├── tsconfig.base.json │ │ ├── tsconfig.json │ │ └── types │ │ │ └── index.d.ts │ └── invalid │ │ ├── placeholder.ts │ │ └── tsconfig.json ├── normalize-trigger-header-methods │ ├── group-only.ts │ ├── multi-group-only.ts │ ├── multi-mixed-only.ts │ ├── multi-trigger-only.ts │ ├── no-only.ts │ ├── trigger-only-in-group-only.ts │ ├── trigger-only-in-group-skip.ts │ └── trigger-only.ts ├── remap-cli │ ├── __snapshots__ │ │ └── example.ts.snap │ ├── empty.ts │ ├── example.ts │ └── remapped.ts ├── remap │ ├── __snapshots__ │ │ ├── example.ts.snap │ │ └── unmatched.ts.snap │ ├── example.ts │ └── unmatched.ts ├── runtime │ └── example.ts └── transform │ ├── all.ts │ ├── commonjs.ts │ ├── multi-line.ts │ └── no-footers.ts ├── jest.json ├── package.json ├── renovate.json ├── reporter.js ├── src ├── __snapshots__ │ ├── remap-cli.test.ts.snap │ ├── remap.test.ts.snap │ ├── reporter.test.ts.snap │ ├── runtime.test.ts.snap │ └── transform.test.ts.snap ├── definitions.ts ├── helpers │ ├── cwd-serializer.ts │ ├── load-fixture.ts │ ├── trigger-header-serializer.ts │ └── version-serializer.ts ├── index.test.ts ├── index.ts ├── remap-cli-parser.ts ├── remap-cli.test.ts ├── remap-cli.ts ├── remap.test.ts ├── remap.ts ├── reporter.test.ts ├── reporter.ts ├── runtime.test.ts ├── runtime.ts ├── setup.ts ├── transform.test.ts ├── transform.ts └── utils │ ├── __snapshots__ │ ├── apply-grouping.test.ts.snap │ ├── create-assertion-expression.test.ts.snap │ ├── create-message.test.ts.snap │ ├── create-setup-expression.test.ts.snap │ ├── create-snapshots.test.ts.snap │ ├── find-docblock-options.test.ts.snap │ ├── find-trigger-bodies.test.ts.snap │ ├── find-trigger-footers.test.ts.snap │ ├── find-trigger-headers.test.ts.snap │ ├── find-triggers.test.ts.snap │ ├── get-comment-content.test.ts.snap │ ├── indent.test.ts.snap │ ├── load-compiler-options.test.ts.snap │ ├── normalize-expected-value.test.ts.snap │ ├── normalize-trigger-header-methods.test.ts.snap │ ├── parse-trigger-header-flags.test.ts.snap │ └── traverse-node.test.ts.snap │ ├── apply-grouping.test.ts │ ├── apply-grouping.ts │ ├── create-assertion-expression.test.ts │ ├── create-assertion-expression.ts │ ├── create-group-expression.ts │ ├── create-message.test.ts │ ├── create-message.ts │ ├── create-setup-expression.test.ts │ ├── create-setup-expression.ts │ ├── create-snapshots.test.ts │ ├── create-snapshots.ts │ ├── create-source-file.ts │ ├── create-test-expression.ts │ ├── create-typescript-info.ts │ ├── find-docblock-options.test.ts │ ├── find-docblock-options.ts │ ├── find-trigger-bodies.test.ts │ ├── find-trigger-bodies.ts │ ├── find-trigger-footers.test.ts │ ├── find-trigger-footers.ts │ ├── find-trigger-headers.test.ts │ ├── find-trigger-headers.ts │ ├── find-triggers.test.ts │ ├── find-triggers.ts │ ├── for-each-comment.ts │ ├── get-comment-content.test.ts │ ├── get-comment-content.ts │ ├── get-description-for-jest.ts │ ├── get-diagnostic-message.ts │ ├── get-display-line.ts │ ├── get-group-description.ts │ ├── get-node-one-line-text.ts │ ├── get-snapshot-description.ts │ ├── get-trigger-groups.ts │ ├── get-trigger-line.ts │ ├── indent.test.ts │ ├── indent.ts │ ├── load-compiler-options.test.ts │ ├── load-compiler-options.ts │ ├── load-typescript.ts │ ├── normalize-config.ts │ ├── normalize-expected-value.test.ts │ ├── normalize-expected-value.ts │ ├── normalize-trigger-header-methods.test.ts │ ├── normalize-trigger-header-methods.ts │ ├── parse-trigger-header-flags.test.ts │ ├── parse-trigger-header-flags.ts │ ├── replace-cwd.ts │ ├── traverse-node.test.ts │ └── traverse-node.ts ├── tests ├── __snapshots__ │ └── example.ts.snap ├── example.snap.ts ├── example.ts └── jest.json ├── transform.js ├── tsconfig.build.json ├── tsconfig.json └── yarn.lock /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = space 5 | indent_size = 2 6 | end_of_line = lf 7 | insert_final_newline = true 8 | trim_trailing_whitespace = true 9 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | * text eol=lf 2 | *.png binary 3 | -------------------------------------------------------------------------------- /.github/workflows/test.yml: -------------------------------------------------------------------------------- 1 | name: Test 2 | 3 | on: 4 | - push 5 | - pull_request 6 | 7 | jobs: 8 | test: 9 | name: Test 10 | strategy: 11 | matrix: 12 | version: [12, lts/*] 13 | runs-on: ubuntu-latest 14 | steps: 15 | - name: Checkout Repository 16 | uses: actions/checkout@v3 17 | 18 | - name: Setup Node.js 19 | uses: actions/setup-node@v3 20 | with: 21 | node-version: ${{ matrix.version }} 22 | cache: 'yarn' 23 | 24 | - name: Install Dependencies 25 | run: yarn 26 | 27 | - name: Lint 28 | run: yarn run lint 29 | 30 | - name: Test 31 | run: yarn run test -- --ci --verbose --coverage 32 | 33 | - name: Test Integration 34 | run: yarn run test-integration -- --ci --verbose 35 | 36 | - name: Test Remap 37 | run: yarn run remap-integration -- --check --list-different 38 | 39 | - name: Upload Coverage 40 | uses: codecov/codecov-action@v2 41 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | coverage/ 2 | lib/ 3 | node_modules/ 4 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ikatyang/dts-jest/86823fe5959be5143842f93c65cc7fafc63bdd64/.npmignore -------------------------------------------------------------------------------- /.prettierrc.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | singleQuote: true, 3 | trailingComma: 'all', 4 | arrowParens: 'avoid', 5 | }; 6 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. 4 | 5 | ### [26.0.2](https://github.com/ikatyang/dts-jest/compare/v26.0.1...v26.0.2) (2024-02-25) 6 | 7 | * v26.0.1 has been unpublished due to missing files on npm, publish again to address the issue 8 | 9 | ### [26.0.1](https://github.com/ikatyang/dts-jest/compare/v26.0.0...v26.0.1) (2024-02-25) 10 | 11 | 12 | ### Bug Fixes 13 | 14 | * compatible with Jest 30 ([#416](https://github.com/ikatyang/dts-jest/issues/416)) ([9fec19f](https://github.com/ikatyang/dts-jest/commit/9fec19fe75bcc81d4351a2085fa769d77fea73fb)) 15 | 16 | ## [26.0.0](https://github.com/ikatyang/dts-jest/compare/v25.0.0...v26.0.0) (2023-04-07) 17 | 18 | 19 | ### ⚠ BREAKING CHANGES 20 | 21 | * TypeScript 4 is now the minimal supported version 22 | 23 | ### Features 24 | 25 | * support TypeScript 5 ([0237ac6](https://github.com/ikatyang/dts-jest/commit/0237ac6df3e921d384be2222bea2165c5a74ab9e)) 26 | 27 | ## [25.0.0](https://github.com/ikatyang/dts-jest/compare/v24.0.0...v25.0.0) (2022-05-14) 28 | 29 | 30 | ### Features 31 | 32 | * support Jest 28 ([4ccfe7a](https://github.com/ikatyang/dts-jest/commit/4ccfe7aed77b44379f0c78be75cb8a684dc30791)) 33 | 34 | 35 | ### BREAKING CHANGES 36 | 37 | * Jest 28 is now the minimal supported version 38 | 39 | 40 | 41 | 42 | # [24.0.0](https://github.com/ikatyang/dts-jest/compare/v23.3.0...v24.0.0) (2021-05-30) 43 | 44 | 45 | ### Features 46 | 47 | * support Jest 27 ([867d3dd](https://github.com/ikatyang/dts-jest/commit/867d3dd)) 48 | 49 | 50 | ### BREAKING CHANGES 51 | 52 | * Jest 27 is now the minimal supported version 53 | 54 | 55 | 56 | 57 | # [23.3.0](https://github.com/ikatyang/dts-jest/compare/v23.2.0...v23.3.0) (2020-08-12) 58 | 59 | 60 | ### Features 61 | 62 | * **deps:** upgrade yargs to 14.x ([#396](https://github.com/ikatyang/dts-jest/issues/396)) ([4584254](https://github.com/ikatyang/dts-jest/commit/4584254)) 63 | 64 | 65 | 66 | 67 | # [23.2.0](https://github.com/ikatyang/dts-jest/compare/v23.1.0...v23.2.0) (2020-07-29) 68 | 69 | 70 | ### Features 71 | 72 | * add `:not-any` flag ([#394](https://github.com/ikatyang/dts-jest/issues/394)) ([7ecd983](https://github.com/ikatyang/dts-jest/commit/7ecd983)) 73 | 74 | 75 | 76 | 77 | # [23.1.0](https://github.com/ikatyang/dts-jest/compare/v23.0.0...v23.1.0) (2020-06-27) 78 | 79 | 80 | ### Features 81 | 82 | * support `@ts-expect-error` ([60451a3](https://github.com/ikatyang/dts-jest/commit/60451a3)) 83 | 84 | 85 | 86 | 87 | # [23.0.0](https://github.com/ikatyang/dts-jest/compare/v22.0.4...v23.0.0) (2019-04-13) 88 | 89 | 90 | ### Chores 91 | 92 | * update dependencies ([#324](https://github.com/ikatyang/dts-jest/issues/324)) ([937b81a](https://github.com/ikatyang/dts-jest/commit/937b81a)) 93 | 94 | 95 | ### Features 96 | 97 | * support jest 22+ ([#325](https://github.com/ikatyang/dts-jest/issues/325)) ([4416e76](https://github.com/ikatyang/dts-jest/commit/4416e76)) 98 | 99 | 100 | ### BREAKING CHANGES 101 | 102 | * drop support for jest < 22 103 | * drop support for node v4 104 | 105 | 106 | 107 | 108 | ## [22.0.4](https://github.com/ikatyang/dts-jest/compare/v22.0.3...v22.0.4) (2018-06-27) 109 | 110 | 111 | ### Bug Fixes 112 | 113 | * **deps:** update dependency yargs to ^9.0.0 ([#102](https://github.com/ikatyang/dts-jest/issues/102)) ([67be7f5](https://github.com/ikatyang/dts-jest/commit/67be7f5)) 114 | * support `typeRoots` ([#252](https://github.com/ikatyang/dts-jest/issues/252)) ([b918aa8](https://github.com/ikatyang/dts-jest/commit/b918aa8)) 115 | 116 | 117 | 118 | 119 | ## [22.0.3](https://github.com/ikatyang/dts-jest/compare/v22.0.2...v22.0.3) (2017-09-05) 120 | 121 | 122 | ### Bug Fixes 123 | 124 | * **deps:** update dependency pretty-format to ^21.0.0 ([#88](https://github.com/ikatyang/dts-jest/issues/88)) ([3721a48](https://github.com/ikatyang/dts-jest/commit/3721a48)) 125 | * **peerDeps:** accept jest ^21.0.0 ([#89](https://github.com/ikatyang/dts-jest/issues/89)) ([fc47496](https://github.com/ikatyang/dts-jest/commit/fc47496)) 126 | 127 | 128 | 129 | 130 | ## [22.0.2](https://github.com/ikatyang/dts-jest/compare/v22.0.1...v22.0.2) (2017-09-04) 131 | 132 | 133 | ### Bug Fixes 134 | 135 | * **options:** add `` placeholder for `typescript` option to better describe its path ([#86](https://github.com/ikatyang/dts-jest/issues/86)) ([a003a31](https://github.com/ikatyang/dts-jest/commit/a003a31)) 136 | 137 | 138 | 139 | 140 | ## [22.0.1](https://github.com/ikatyang/dts-jest/compare/v22.0.0...v22.0.1) (2017-09-01) 141 | 142 | 143 | ### Bug Fixes 144 | 145 | * **runtime:** show 1-based line number ([#82](https://github.com/ikatyang/dts-jest/issues/82)) ([de4c6aa](https://github.com/ikatyang/dts-jest/commit/de4c6aa)) 146 | 147 | 148 | 149 | 150 | # [22.0.0](https://github.com/ikatyang/dts-jest/compare/v21.0.0...v22.0.0) (2017-08-31) 151 | 152 | 153 | ### Bug Fixes 154 | 155 | * **deps:** jest peerDeps should allow ^20.0.0 ([1a24239](https://github.com/ikatyang/dts-jest/commit/1a24239)) 156 | * report unmatched diagnostic ([#52](https://github.com/ikatyang/dts-jest/issues/52)) ([4ab0f86](https://github.com/ikatyang/dts-jest/commit/4ab0f86)) 157 | * **deps:** update peerDeps typescript to ^2.3.0 ([c075dd2](https://github.com/ikatyang/dts-jest/commit/c075dd2)) 158 | 159 | ### Features 160 | 161 | * add ability to specify which typescript to use ([#49](https://github.com/ikatyang/dts-jest/issues/49)) ([9213bc1](https://github.com/ikatyang/dts-jest/commit/9213bc1)) 162 | * add reporter to show current TS version ([#51](https://github.com/ikatyang/dts-jest/issues/51)) ([bf4ee48](https://github.com/ikatyang/dts-jest/commit/bf4ee48)) 163 | * combine type and value tests ([#69](https://github.com/ikatyang/dts-jest/issues/69)) ([876b37d](https://github.com/ikatyang/dts-jest/commit/876b37d)) 164 | * redefine flags ([#54](https://github.com/ikatyang/dts-jest/issues/54)) ([dc1883f](https://github.com/ikatyang/dts-jest/commit/dc1883f)) 165 | * rewrite remap & remap-cli ([#59](https://github.com/ikatyang/dts-jest/issues/59)) ([1db5ea0](https://github.com/ikatyang/dts-jest/commit/1db5ea0)) 166 | * show detailed test title ([#74](https://github.com/ikatyang/dts-jest/issues/74)) ([2eac61f](https://github.com/ikatyang/dts-jest/commit/2eac61f)) 167 | * support `tsconfig.json` literal options ([#56](https://github.com/ikatyang/dts-jest/issues/56)) ([f9dd34a](https://github.com/ikatyang/dts-jest/commit/f9dd34a)) 168 | 169 | 170 | ### BREAKING CHANGES 171 | 172 | * **deps:** drop TS < v2.3 173 | * **transform-actual:** remove transformer `transform-actual` as it currently combined with `transform` 174 | * **remap:** [API] `remap(...)` 175 | * before 176 | * `snapshot_content` 177 | * allow `string` (raw content from *.snap) 178 | * allow `Record` (unparsed content from *.snap) 179 | * after 180 | * `snapshot_content` 181 | * allow `string` (raw content from *.snap) 182 | * allow `Record` (parsed content from *.snap) 183 | * **remap-cli:** rename bin from `dts-jest-remap-snapshot` to `dts-jest-remap` 184 | * input using source file instead of snapshot file, e.g. 185 | * before: `./__snapshots__/example.ts.snap` 186 | * after: `./example.ts` 187 | * output content does not print to stdout now, use `--outDir` and `--rename` to specify output path instead 188 | * **configs:** replace config value with config literal 189 | * Before 190 | ```json5 191 | { 192 | "target": 5 // ts.ScriptTarget.ESNext 193 | } 194 | ``` 195 | * After 196 | ```json 197 | { 198 | "target": "esnext" 199 | } 200 | ``` 201 | * **flags:** redefine flag 202 | * type tests 203 | * `@dts-jest` -> `@dts-jest:snapshot` 204 | * `@dts-jest:snap` -> `@dts-jest:snapshot` 205 | * `@dts-jest:pass` -> `@dts-jest:pass:snapshot` 206 | * `@dts-jest:fail` -> `@dts-jest:fail:snapshot` 207 | * actual tests 208 | * `@dts-jest` + `//=> value` -> `//=> :no-error` 209 | * `@dts-jest:snap` + `//=> value` -> `//=> :no-error` 210 | * `@dts-jest:show` + `//=> value` -> `//=> ?` 211 | * `@dts-jest:pass` + `//=> value` -> `//=> value` 212 | * `@dts-jest:fail` + `//=> value` -> `//=> :error` 213 | 214 | 215 | # [21.0.0](https://github.com/ikatyang/dts-jest/compare/v20.5.1...v21.0.0) (2017-08-18) 216 | 217 | 218 | ### Features 219 | 220 | * **deps:** move typescript to peerDependecies ([#38](https://github.com/ikatyang/dts-jest/issues/38)) ([e9800f1](https://github.com/ikatyang/dts-jest/commit/e9800f1)) 221 | 222 | 223 | ### BREAKING CHANGES 224 | 225 | * **deps:** TypeScript now has to be installed manually so that you can choose which version to use 226 | 227 | * **version:** This project now **DOES NOT** use the same versioning as Jest 228 | 229 | 230 | ## v20.5.1 (2017-06-30) 231 | 232 | #### 🚀 New Feature 233 | - allow using snapshot-content object for `remap-snapshot` 234 | - allow specifying snapshot filename for `remap-snapshot` so as to handle cache 235 | 236 | ## v20.5.0 (2017-06-30) 237 | 238 | #### 🚀 New Feature 239 | - Add `remap-snapshot` to generate diff-friendly snapshots 240 | 241 | ## v20.4.1 (2017-06-24) 242 | 243 | #### 🐛 Bug Fix 244 | - Fix transpile error for actual test 245 | 246 | ## v20.4.0 (2017-06-24) 247 | 248 | #### 🚀 New Feature 249 | - Add actual test transformer (`dts-jest/transform-actual`) with `//=> value` comment 250 | 251 | ## v20.3.1 (2017-06-21) 252 | 253 | #### 🐛 Bug Fix 254 | - Fix indentation for description of grouped test 255 | 256 | ## v20.3.0 (2017-06-21) 257 | 258 | #### 🚀 New Feature 259 | - Add group flag to categorize test cases 260 | - Add default flags ( `:test`, `:shot` ) to show its explicit flag 261 | - Allow to set flags with any order, e.g. `:show:only`, `:only:show` 262 | 263 | #### 🐛 Bug Fix 264 | - Remove unnecessary leading spaces in expressions (dedent) 265 | 266 | ## v20.2.0 (2017-06-20) 267 | 268 | #### 🚀 New Feature 269 | - Add flags ( `:pass`, `:fail`, `:only:pass`, `:only:fail` ) to assert its result 270 | 271 | ## v20.1.0 (2017-06-13) 272 | 273 | #### 💥 Breaking Change 274 | - Use same MAJOR version as Jest 275 | - Remove server since tests should be separated 276 | 277 | #### 🚀 New Feature 278 | - Add config `type_format` 279 | - Display description in `:show` 280 | 281 | ## v20.0.6 (2017-06-10) 282 | 283 | #### 🐛 Bug Fix 284 | - Fix transforming for template token 285 | 286 | ## v20.0.4 (2017-06-09) 287 | 288 | #### 🐛 Bug Fix 289 | - Fix unexpected filenames 290 | 291 | #### 🏠 Internal 292 | - Use POST for modification actions 293 | 294 | ## v20.0.3 (2017-06-03) 295 | 296 | #### 💥 Breaking Change 297 | - setup a server for initializing TS source file at once 298 | - remove useless config `type_detail`, `type_format`, `snapshot_formatter` 299 | 300 | #### 🚀 New Feature 301 | - allow to use `` in config `tsconfig` 302 | 303 | ## v20.0.2 (2017-05-16) 304 | 305 | #### 🐛 Bug Fix 306 | - Fix missing config 307 | 308 | ## v20.0.1 (2017-05-16) 309 | 310 | #### 🚀 New Feature 311 | - detect unattachable triggers 312 | - allow to customize `:show` message with `reporter` option 313 | - allow to customize inferred type with `type_detail` and `type_format` option 314 | - allow to customize snapshot content with `snapshot_formatter` option 315 | 316 | #### 🏠 Internal 317 | - rewrite for better user experience about cache 318 | 319 | ## v20.0.0 (2017-05-14) 320 | 321 | #### 🚀 New Feature 322 | - Use same MAJOR.MINOR version as Jest 323 | 324 | #### 📝 Documentation 325 | - Fix image urls in README.md 326 | 327 | ## v1.0.5 (2017-05-13) 328 | 329 | #### 🐛 Bug Fix 330 | - Fix dependency 331 | 332 | ## v1.0.4 (2017-05-13) 333 | 334 | #### 🚀 New Feature 335 | - Release first version 336 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) Ika (https://github.com/ikatyang) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # dts-jest 2 | 3 | [![npm](https://img.shields.io/npm/v/dts-jest.svg)](https://www.npmjs.com/package/dts-jest) 4 | [![build](https://img.shields.io/travis/ikatyang/dts-jest/master.svg)](https://travis-ci.org/ikatyang/dts-jest/builds) 5 | [![coverage](https://img.shields.io/codecov/c/github/ikatyang/dts-jest.svg)](https://codecov.io/gh/ikatyang/dts-jest) 6 | 7 | A 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 8 | 9 | [Changelog](https://github.com/ikatyang/dts-jest/blob/master/CHANGELOG.md) 10 | 11 | - [Install](#install) 12 | - [Usage](#usage) 13 | - [Writing Tests](#writing-tests) 14 | - [Patterns](#patterns) 15 | - [Patterns for Testing](#patterns-for-testing) 16 | - [Patterns for Grouping](#patterns-for-grouping) 17 | - [Patterns for File-Level Config](#patterns-for-file-level-config) 18 | - [Testing](#testing) 19 | - [Configs](#configs) 20 | - [Generate diff-friendly snapshots](#generate-diff-friendly-snapshots) 21 | - [Reporter](#reporter) 22 | - [FAQ](#faq) 23 | - [Development](#development) 24 | - [Related](#related) 25 | - [License](#license) 26 | 27 | ## Install 28 | 29 | ```sh 30 | # using npm 31 | npm install --save-dev dts-jest jest typescript 32 | 33 | # using yarn 34 | yarn add --dev dts-jest jest typescript 35 | ``` 36 | 37 | - require `jest@>=28` and `typescript@>=4` 38 | 39 | | dts-jest | jest | typescript | 40 | | -------- | -------- | ---------- | 41 | | 26 | >=28 | >=4 | 42 | | 25 | >=28 <30 | >=2.3 <5 | 43 | | 24 | 27 | >=2.3 <5 | 44 | | 23 | >=22 <27 | >=2.3 <5 | 45 | 46 | ## Usage 47 | 48 | Modify your [Jest config](https://facebook.github.io/jest/docs/en/configuration.html) so that looks something like: 49 | 50 | (./package.json) 51 | 52 | ```json 53 | { 54 | "scripts": { 55 | "test": "jest" 56 | }, 57 | "jest": { 58 | "moduleFileExtensions": ["ts", "js", "json"], 59 | "testRegex": "/dts-jest/.+\\.ts$", 60 | "transform": {"/dts-jest/.+\\.ts$": "dts-jest/transform"} 61 | } 62 | } 63 | ``` 64 | 65 | This setup allow you to test files `**/dts-jest/**/*.ts` via `dts-jest`. 66 | 67 | ## Writing Tests 68 | 69 | The 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. 70 | 71 | (./dts-jest/example.ts) 72 | 73 | ```ts 74 | // @dts-jest:pass:snap 75 | Math.max(1); 76 | 77 | // @dts-jest:pass 78 | Math.min(1, 2, 3); //=> 1 79 | 80 | // @dts-jest:fail:snap 81 | Math.max('123'); 82 | 83 | // @ts-expect-error:snap 84 | Math.max('123'); 85 | ``` 86 | 87 | ## Patterns 88 | 89 | ### Patterns for Testing 90 | 91 | ```ts 92 | // @dts-jest[flags] [description] 93 | expression //=> expected 94 | 95 | // @ts-expect-error[flags] [description] 96 | expression //=> expected 97 | ``` 98 | 99 | _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`. 100 | 101 | - description 102 | - optional 103 | - default: `expression` 104 | - flag 105 | - optional 106 | - for test 107 | - default: [`test`](https://facebook.github.io/jest/docs/en/api.html#testname-fn) 108 | - `:only`: [`test.only`](https://facebook.github.io/jest/docs/en/api.html#testonlyname-fn) 109 | - `:skip`: [`test.skip`](https://facebook.github.io/jest/docs/en/api.html#testskipname-fn) 110 | - for type assertion 111 | - default: none 112 | - `:show`: `console.log(type)` 113 | - `:pass`: `expect(() => type)`[`.not`](https://facebook.github.io/jest/docs/en/expect.html#not)[`.toThrow()`](https://facebook.github.io/jest/docs/en/expect.html#tothrowerror) 114 | - `:fail`: `expect(() => type)`[`.toThrow()`](https://facebook.github.io/jest/docs/en/expect.html#tothrowerror) 115 | - `:snap`: 116 | - snapshot inferred type or diagnostic message 117 | - `expect(type)`[`.toMatchSnapshot()`](https://facebook.github.io/jest/docs/en/expect.html#tomatchsnapshotoptionalstring) 118 | - `expect(type)`[`.toThrowErrorMatchingSnapshot()`](https://facebook.github.io/jest/docs/en/expect.html#tothrowerrormatchingsnapshot) 119 | - `: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) 120 | - expected 121 | - optional 122 | - `//=> expected` or `/*=> expected */` 123 | - for value assertion 124 | - default: none 125 | - `?`: `console.log(value)` 126 | - `:error`: `expect(() => value)`[`.toThrow()`](https://facebook.github.io/jest/docs/en/expect.html#tothrowerror) 127 | - `:no-error`: `expect(() => value)`[`.not`](https://facebook.github.io/jest/docs/en/expect.html#not)[`.toThrow()`](https://facebook.github.io/jest/docs/en/expect.html#tothrowerror) 128 | - others: `expect(value)`[`.toEqual(expected)`](https://facebook.github.io/jest/docs/en/expect.html#toequalvalue) 129 | 130 | ### Patterns for Grouping 131 | 132 | Test cases after this pattern will be marked as that group. 133 | 134 | ```ts 135 | // @dts-jest:group[flag] [description] 136 | ``` 137 | 138 | If you need a block scope for your tests you can use a Block Statement. 139 | 140 | ```ts 141 | // @dts-jest:group[flag] [description] 142 | { 143 | // your tests 144 | } 145 | ``` 146 | 147 | - description 148 | - default: `''` 149 | - flag 150 | - default: [`describe`](https://facebook.github.io/jest/docs/en/api.html#describename-fn) 151 | - `:only`: [`describe.only`](https://facebook.github.io/jest/docs/en/api.html#describeonlyname-fn) 152 | - `:skip`: [`describe.skip`](https://facebook.github.io/jest/docs/en/api.html#describeskipname-fn) 153 | 154 | ### Patterns for File-Level Config 155 | 156 | File-level config uses the first comment to set, only docblock will be detected. 157 | 158 | ```ts 159 | /** @dts-jest [action:option] ... */ 160 | ``` 161 | 162 | - action: 163 | - `enable`: set to `true` 164 | - `disable`: set to `false` 165 | - option: 166 | - `test-type`: `test_type` option in [configs](#configs) 167 | - `test-value`: `test_value` option in [configs](#configs) 168 | 169 | ## Testing 170 | 171 | It's recommended you to run Jest in watching mode via `--watch` flag. 172 | 173 | ```sh 174 | npm run test -- --watch 175 | ``` 176 | 177 | **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. 178 | 179 | After running the [example tests](#writing-tests) with `npm run test`, you'll get the following result: 180 | 181 | ```text 182 | PASS tests/example.ts 183 | Math.max(1) 184 | ✓ (type) should not throw error 185 | ✓ (type) should match snapshot 186 | Math.max('123') 187 | ✓ (type) should throw error 188 | ✓ (type) should match snapshot 189 | Math.min(1, 2, 3) 190 | ✓ (type) should not throw error 191 | 192 | Snapshot Summary 193 | › 2 snapshots written in 1 test suite. 194 | 195 | Test Suites: 1 passed, 1 total 196 | Tests: 5 passed, 5 total 197 | Snapshots: 2 added, 2 total 198 | Time: 0.000s 199 | Ran all test suites. 200 | ``` 201 | 202 | Since 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. 203 | 204 | (./dts-jest/example.ts) 205 | 206 | ```ts 207 | // @dts-jest:pass:show 208 | Math.max(1); 209 | 210 | // @dts-jest:fail:show 211 | Math.max('123'); 212 | 213 | // @dts-jest:pass 214 | Math.min(1, 2, 3); //=> 1 215 | ``` 216 | 217 | ```text 218 | PASS dts-jest/example.ts 219 | Math.max(1) 220 | ✓ (type) should show report 221 | ✓ (type) should not throw error 222 | Math.max('123') 223 | ✓ (type) should show report 224 | ✓ (type) should throw error 225 | Math.min(1, 2, 3) 226 | ✓ (type) should not throw error 227 | 228 | Test Suites: 1 passed, 1 total 229 | Tests: 5 passed, 5 total 230 | Snapshots: 0 total 231 | Time: 0.000s 232 | Ran all test suites. 233 | 234 | console.log dts-jest/example.ts:2 235 | 236 | Inferred 237 | 238 | Math.max(1) 239 | 240 | to be 241 | 242 | number 243 | 244 | console.log dts-jest/example.ts:5 245 | 246 | Inferring 247 | 248 | Math.max('123') 249 | 250 | but throw 251 | 252 | Argument of type '"123"' is not assignable to parameter of type 'number'. 253 | ``` 254 | 255 | ## Configs 256 | 257 | Configs are in `_dts_jest_` field of Jest config `globals`. 258 | 259 | There are several options 260 | 261 | - test_type 262 | - default: `true` 263 | - enable type testing 264 | - [file-level config](#patterns-for-file-level-config) available 265 | - test_value 266 | - default: `false` 267 | - enable value testing 268 | - [file-level config](#patterns-for-file-level-config) available 269 | - enclosing_declaration 270 | - default: `false` 271 | - unwrap type alias 272 | - typescript 273 | - default: `typescript` (node resolution) 274 | - specify which path of typescript to use 275 | - `` available 276 | - compiler_options 277 | - default: `{}` 278 | - specify which *path of `tsconfig.json` (string)* ~~or *compilerOptions (object)*~~ (deprecated, does not support `typeRoots` for _object_) to use 279 | - type_format_flags 280 | - default: `ts.TypeFormatFlags.NoTruncation` 281 | - specify type format 282 | - transpile 283 | - default: `true` 284 | - transpile code before testing, only affect tests that needs to test value 285 | - transpiling code will cause line number incorrect, it's better to disable this option if possible 286 | 287 | For example: 288 | 289 | (./package.json) 290 | 291 | ```json 292 | { 293 | "jest": { 294 | "globals": { 295 | "_dts_jest_": { 296 | "compiler_options": { 297 | "strict": true, 298 | "target": "es6" 299 | } 300 | } 301 | } 302 | } 303 | } 304 | ``` 305 | 306 | ## Generate diff-friendly snapshots 307 | 308 | Originally, 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. 309 | 310 | (./tests/example.ts) 311 | 312 | ```ts 313 | // @dts-jest:snap 314 | Math.max(1, 2, 3); 315 | ``` 316 | 317 | (./tests/`__snapshots__`/example.ts.snap) note this file is generated by Jest 318 | 319 | ```ts 320 | // Jest Snapshot v1, https://goo.gl/fbAQLP 321 | exports[`Math.max(1, 2, 3) 1`] = `"number"`; 322 | ``` 323 | 324 | This command will combine both snapshots and source content in one file: 325 | 326 | ```sh 327 | dts-jest-remap ./tests/example.ts --outDir ./snapshots 328 | ``` 329 | 330 | (./snapshots/example.ts) 331 | 332 | ```ts 333 | // @dts-jest:snap -> number 334 | Math.max(1, 2, 3); 335 | ``` 336 | 337 | ```text 338 | Usage: dts-jest-remap [--outDir ] [--rename