From 315365e86b7e15d5bc725cd61dd8b1893f7c5fad Mon Sep 17 00:00:00 2001
From: Rhys Evans <wheresrhys@gmail.com>
Date: Fri, 20 Sep 2024 15:35:42 +0100
Subject: [PATCH] docs: fix mistakes in codemods docs

---
 packages/codemods/README.md | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/packages/codemods/README.md b/packages/codemods/README.md
index 4cf42a7a..c85ddda7 100644
--- a/packages/codemods/README.md
+++ b/packages/codemods/README.md
@@ -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`
@@ -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