Skip to content

Commit

Permalink
docs: fix mistakes in codemods docs
Browse files Browse the repository at this point in the history
  • Loading branch information
wheresrhys committed Sep 20, 2024
1 parent 2d18b63 commit 315365e
Showing 1 changed file with 20 additions and 10 deletions.
30 changes: 20 additions & 10 deletions packages/codemods/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,27 @@ A tool for helping upgrade to fetch-mock@12.

## Usage

1. Install `npm i -D @fetch-mock/codemods jscodeshift`;
2. Manually modify any code using `.sandbox()` according to the example above.
3. Run `jscodeshift -t node_modules/@fetch-mock/codemods/wrc/index.jscodeshift .` to run over your entire project, or replace `.` with the directory/file paths you wish to modify. [The jscodeshift CLI has many options](https://jscodeshift.com/run/cli/) - adjust them to suit your project. **Note that the parser option should not be used as @fetch-mock/codemods forces use of the TSX parser in order to ensure compatibility with teh greatest range of projects**.
4. For scenarios where the codemod is unable to detect which variable contains a fetch-mock instance (e.g. when it is required in a global set up file, or when using `jest.mock()`) you may pass in one or more variable names using the `FM_VARIABLES` environment variable e.g. `FM_VARIABLES=fm,fetch`
5. After the codemods have executed, run your tests, correcting all the errors thrown. The notes on what is in/out of scope will help guide you.
1. Install `npm i -D @fetch-mock/codemods jscodeshift fetch-mock@12`;
2. Manually modify any code using `.sandbox()` according to the example at the bottom of this page.
3. Run `jscodeshift -t node_modules/@fetch-mock/codemods/src/index.js --ignore-pattern="node_modules/**/*" .` to run over your entire project, or replace `.` with the directory/file paths you wish to modify. [The jscodeshift CLI has many options](https://jscodeshift.com/run/cli/) - adjust them to suit your project. **Note that the parser option should not be used as @fetch-mock/codemods forces use of the TSX parser in order to ensure compatibility with teh greatest range of projects**.
4. For scenarios where the codemod is unable to detect which variable contains a fetch-mock instance (e.g. when it is required in a global set up file, or when using `jest.mock()` or fetch-mock-jest) you may pass in one or more variable names using the `FM_VARIABLES` environment variable e.g. `FM_VARIABLES=fm,fetch`
5. After the codemods have executed:
a) If mocking global `fetch` you will probably need to add a call to `.mockGlobal()` at least once per test suite, possibly in a `beforeAll`/`beforeEach` block.
b) Correct all the errors inserted by the codemod related to use of `fallbackToNetwork`, `.calls()` or `.lastCall()` usage.
c) Run all your tests and fix any issues. If you believe the codemods have made any errors, or have missed any easy to modify patterns, please [raise an issue](https://github.com/wheresrhys/fetch-mock/issues).
6. Once all your tests are fixed you should be able to uninstall the codemods: `npm uninstall @fetch-mock/codemods jscodeshift`

## Features
### Usage with fetch-mock-jest

- Identifies instances of fetch-mock imported using `require` or `import`
- Rewrites `.mock()` to `.route()`
- Rewrites `.reset()`, `.restore()`, `.resetBehavior()` and `.resetHistory()` to their equivalents in fetch-mock@12
- Rewrites `.lastUrl()`, `.lastOptions()` and `lastResponse()` to their equivalents in fetch-mock@12
If you're using fetch-mock-jest, you should migrate to @fetch-mock/jest, which is built around fetch-mock@12. While these codemods have not been tested on fetch-mock-jest, in principle you should be able use them by making similar adjustments to those described below about use with the `sandbox()` method, and by using the `FM_VARIABLES` environment variable to help the codemod identify which variables contain instances of fetch-mock.

## Modifications that will be made

For everyt variable containing an instance of fetch-mock imported using `require` or `import` it will:

- Rewrite `.mock()` to `.route()`
- Rewrite `.reset()`, `.restore()`, `.resetBehavior()` and `.resetHistory()` to their equivalents in fetch-mock@12
- Rewrite `.lastUrl()`, `.lastOptions()` and `lastResponse()` to their equivalents in fetch-mock@12
- Adds an informative error whenever `.lastCall()` or `.calls()` are used with advice on how to manually correct these
- Converts `.getOnce()`, `.getAnyOnce()`, `.postOnce()` etc... - which have been removed - to calls to the underlying `.get()` method with additional options passed in.
- Removes uses of the deprecated options `overwriteRoutes`, `warnOnFallback`, `sendAsJson`
Expand All @@ -32,6 +40,8 @@ A tool for helping upgrade to fetch-mock@12.
- When using a pattern such as `jest.mock('node-fetch', () => require('fetch-mock').sandbox())`, the codemod is unable to identify that `require('node-fetch')` will be an instance of fetch-mock.
- On the server side fetch-mock was previously built around node-fetch's classes, but now uses native `fetch`. In most cases, even if your application code still uses node-fetch, your mocks will still work. However, if you explicitly create instances of `Request` or `Headers` using node-fetch's classes, you may need to provide these to fetch-mock.

## Manual adjustments when working with sandbox()

Taking the last 4 points together, this example illustrates the kind of manual modifications required:

### Before
Expand Down

0 comments on commit 315365e

Please sign in to comment.