Doctor Mode (--doctor)

Doctor mode is a powerful feature that iteratively installs upgrades and runs your project's tests to identify breaking changes automatically. It helps pinpoint exactly which dependency upgrade causes a test failure.

Usage

To run doctor mode, you must include the -u (--upgrade) flag, as it needs to modify your package.json, node_modules, and lock file to perform tests.

ncu --doctor -u

How It Works

  1. Initial Check: It first runs npm install and npm test (or their equivalents for your package manager) to ensure your tests are currently passing.
  2. Optimistic Upgrade: It performs a full ncu -u to upgrade all dependencies to their latest versions.
  3. Full Test: It runs npm install and npm test again.
    • If the tests pass, the process is complete, and your package.json is saved with all upgrades.
  4. Isolate Breaking Changes: If the tests fail, it restores your original package.json and lock file.
  5. Iterative Testing: It then proceeds to upgrade each dependency one by one, running npm install and npm test after each individual upgrade.
  6. Report and Save:
    • It identifies and reports which upgrades caused the tests to fail.
    • It saves a partially upgraded package.json containing only the upgrades that passed the tests.

Example

Here is an example of the output you might see when doctor mode finds a breaking change:

$ ncu --doctor -u
npm install
npm run test
ncu -u
npm install
npm run test
Failing tests found:
/projects/myproject/test.js:13
  throw new Error('Test failed!')
  ^
Now let’s identify the culprit, shall we?
Restoring package.json
Restoring package-lock.json
npm install
npm install --no-save react@16.0.0
npm run test
  ✓ react 15.0.0 → 16.0.0
npm install --no-save react-redux@7.0.0
npm run test
  ✗ react-redux 6.0.0 → 7.0.0
Saving partially upgraded package.json

Customizing Commands

You can specify custom commands for the install and test steps if your project's setup requires it:

  • --doctorInstall <command>: Specifies the install script (e.g., pnpm install --no-frozen-lockfile).
  • --doctorTest <command>: Specifies the test script (e.g., npm run test:ci).