dts-jest

A preprocessor for Jest to snapshot test TypeScript declaration (.d.ts) files

Changelog

• Install
• Usage
• Writing Tests
• Patterns
  • Patterns for Testing
  • Patterns for Grouping
  • Patterns for File-Level Config
• Testing
• Configs
• Generate diff-friendly snapshots
• Reporter
• FAQ
• Development
• Related
• License

Install

# using npm
npm install --save-dev dts-jest jest typescript

# using yarn
yarn add --dev dts-jest jest typescript

• require jest@>=28 and typescript@>=4

  dts-jest	jest	typescript
  26	>=28	>=4
  25	>=28 <30	>=2.3 <5
  24	27	>=2.3 <5
  23	>=22 <27	>=2.3 <5

Usage

Modify your Jest config so that looks something like:

(./package.json)

{
  "scripts": {
    "test": "jest"
  },
  "jest": {
    "moduleFileExtensions": ["ts", "js", "json"],
    "testRegex": "/dts-jest/.+\\.ts$",
    "transform": {"/dts-jest/.+\\.ts$": "dts-jest/transform"}
  }
}

This setup allow you to test files **/dts-jest/**/*.ts via dts-jest.

Writing Tests

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.

(./dts-jest/example.ts)

// @dts-jest:pass:snap
Math.max(1);

// @dts-jest:pass
Math.min(1, 2, 3); //=> 1

// @dts-jest:fail:snap
Math.max('123');

// @ts-expect-error:snap
Math.max('123');

Patterns

Patterns for Testing

// @dts-jest[flags] [description]
expression //=> expected

// @ts-expect-error[flags] [description]
expression //=> expected

Note: @ts-expect-error is treated as an alias of @dts-jest:fail in dts-jest.

• description
  • optional
  • default: expression
• flag
  • optional
  • for test
    • default: test
    • :only: test.only
    • :skip: test.skip
  • for type assertion
    • default: none
    • :show: console.log(type)
    • :pass: expect(() => type).not.toThrow()
    • :fail: expect(() => type).toThrow()
    • :snap:
      • snapshot inferred type or diagnostic message
      • expect(type).toMatchSnapshot()
      • expect(type).toThrowErrorMatchingSnapshot()
    • :not-any: expect(type).not.toBe("any")
• expected
  • optional
  • //=> expected or /*=> expected */
  • for value assertion
    • default: none
    • ?: console.log(value)
    • :error: expect(() => value).toThrow()
    • :no-error: expect(() => value).not.toThrow()
    • others: expect(value).toEqual(expected)

Patterns for Grouping

Test cases after this pattern will be marked as that group.

// @dts-jest:group[flag] [description]

If you need a block scope for your tests you can use a Block Statement.

// @dts-jest:group[flag] [description]
{
  // your tests
}

• description
  • default: ''
• flag
  • default: describe
  • :only: describe.only
  • :skip: describe.skip

Patterns for File-Level Config

File-level config uses the first comment to set, only docblock will be detected.

/** @dts-jest [action:option] ... */

• action:
  • enable: set to true
  • disable: set to false
• option:
  • test-type: test_type option in configs
  • test-value: test_value option in configs

Testing

It's recommended you to run Jest in watching mode via --watch flag.

npm run test -- --watch

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.

After running the example tests with npm run test, you'll get the following result:

 PASS  tests/example.ts
  Math.max(1)
    ✓ (type) should not throw error
    ✓ (type) should match snapshot
  Math.max('123')
    ✓ (type) should throw error
    ✓ (type) should match snapshot
  Math.min(1, 2, 3)
    ✓ (type) should not throw error

Snapshot Summary
 › 2 snapshots written in 1 test suite.

Test Suites: 1 passed, 1 total
Tests:       5 passed, 5 total
Snapshots:   2 added, 2 total
Time:        0.000s
Ran all test suites.

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.

(./dts-jest/example.ts)

// @dts-jest:pass:show
Math.max(1);

// @dts-jest:fail:show
Math.max('123');

// @dts-jest:pass
Math.min(1, 2, 3); //=> 1

 PASS  dts-jest/example.ts
  Math.max(1)
    ✓ (type) should show report
    ✓ (type) should not throw error
  Math.max('123')
    ✓ (type) should show report
    ✓ (type) should throw error
  Math.min(1, 2, 3)
    ✓ (type) should not throw error

Test Suites: 1 passed, 1 total
Tests:       5 passed, 5 total
Snapshots:   0 total
Time:        0.000s
Ran all test suites.

  console.log dts-jest/example.ts:2

    Inferred

      Math.max(1)

    to be

      number

  console.log dts-jest/example.ts:5

    Inferring

      Math.max('123')

    but throw

      Argument of type '"123"' is not assignable to parameter of type 'number'.

Configs

Configs are in _dts_jest_ field of Jest config globals.

There are several options

• test_type
  • default: true
  • enable type testing
  • file-level config available
• test_value
  • default: false
  • enable value testing
  • file-level config available
• enclosing_declaration
  • default: false
  • unwrap type alias
• typescript
  • default: typescript (node resolution)
  • specify which path of typescript to use
  • `` available
• compiler_options
  • default: {}
  • specify which path of tsconfig.json (string) or compilerOptions (object) (deprecated, does not support typeRoots for object) to use
• type_format_flags
  • default: ts.TypeFormatFlags.NoTruncation
  • specify type format
• transpile
  • default: true
  • transpile code before testing, only affect tests that needs to test value
  • transpiling code will cause line number incorrect, it's better to disable this option if possible

For example:

(./package.json)

{
  "jest": {
    "globals": {
      "_dts_jest_": {
        "compiler_options": {
          "strict": true,
          "target": "es6"
        }
      }
    }
  }
}

Generate diff-friendly snapshots

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.

(./tests/example.ts)

// @dts-jest:snap
Math.max(1, 2, 3);

(./tests/__snapshots__/example.ts.snap) note this file is generated by Jest

// Jest Snapshot v1, https://goo.gl/fbAQLP
exports[`Math.max(1, 2, 3) 1`] = `"number"`;

This command will combine both snapshots and source content in one file:

dts-jest-remap ./tests/example.ts --outDir ./snapshots

(./snapshots/example.ts)

// @dts-jest:snap -> number
Math.max(1, 2, 3);

Usage: dts-jest-remap [--outDir