# Replace the mock Backport With unittest.mock

Yes. An agent replaces the third-party mock package with unittest.mock, fixes the import order your linter enforces and drops the test dependency.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-mock-to-unittest-mock/mock/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The `mock` package on PyPI is a backport of `unittest.mock` for interpreters that lack a recent one. A project that only supports Python 3 can import the standard library's copy and delete a test dependency. The agent's first step is to separate the third-party import from everything else spelled the same way, and in some repositories that takes care. In StackStorm/orquesta, a search for `mock` returns hundreds of lines, because the package has its own `orquesta/specs/mock` and `orquesta/composers/mock.py`, a `mock = orquesta.composers.mock:WorkflowComposer` entry point in `setup.py`, and a house rule in `orquesta/tests/hacking/import_aliases_rule.py` that those modules are imported as `mock_specs` and `mock_models`. The third-party package is imported in exactly one file, `orquesta/tests/unit/commands/test_rehearse_command.py`, as a bare `import mock`, and pinned as `mock==4.0.3` in `requirements-test.txt`.

The edit is one line, `from unittest import mock`, and every `mock.patch.object` and `mock.MagicMock` below it keeps working. The lint configuration is what makes it more than one line. This project runs flake8 with the OpenStack `hacking` plugin, and replacing the line where it stands fails with `H306: imports not in alphabetical order (unittest.mock, unittest)`, because the file already has `import unittest` on the next line. The agent moves the new import below it, then runs the three commands the `pep8` environment in `tox.ini` runs: `pylint -E`, `flake8 --config .flake8` and `black --check -l 100`.

The same plugin has a rule for this exact migration. `H216` reports any import of the third-party package with the message that the `unittest.mock` module should be used instead, and `.flake8` in this repository lists `H216` under `ignore`. Once the last import is gone the exemption has no reason to exist. The agent removes `H216` from `ignore`, adds it to `enable-extensions`, and runs flake8 over the whole `orquesta` package to confirm nothing else trips it. From then on a new `import mock` fails lint instead of quietly bringing the dependency back.

Last, it proves the dependency is unused by removing it. It deletes the `mock==4.0.3` line, uninstalls the package from the environment, and runs the seven tests in the rehearsal command file and then the suite, on each interpreter in the `tox.ini` envlist: 3.10, 3.11 and 3.12. That matrix matters because the standard library's mock is not frozen at the backport's behaviour. On Python 3.12, reading `called_once_with` or `has_calls` from a mock raises `AttributeError` with the text `is not a valid assertion`, where `mock` 4.0.3 returns a child mock and lets a mistyped check pass. The agent searches the tests for those names and reports any it finds as assertions that were never checking anything.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Replace the third-party mock package with the standard library's unittest.mock in this Python project. First confirm every supported Python version is 3.x by reading setup.py or pyproject.toml, tox.ini and the CI matrix; if Python 2 is still supported, stop and report. Find the imports of the third-party package (import mock, from mock import ...) and keep them apart from the project's own modules, fixtures or entry points that happen to be named mock. Rewrite each import to unittest.mock, keeping the local name the file already uses so the test bodies do not change. Read the lint configuration: place the new import where the project's import-order rule wants it, and if the config ignores a rule that exists to forbid the third-party mock import, such as hacking's H216, enable that rule and show the linter passing on the whole package. Remove mock from every requirements file and from tox or CI install steps, uninstall it from the environment, and run the test suite and the project's lint commands on each Python version in the tox envlist. Search the tests for mock attributes that look like assertions but are not, such as called_once_with, has_calls or not_called used without the assert_ prefix, and report each with file and line; fix only the ones that are plainly typos of a real assertion and say what the corrected assertion found. Open a pull request with the lint and test output for each version.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request with three small diffs: the import in `test_rehearse_command.py`, the deleted line in `requirements-test.txt`, and `.flake8` with `H216` moved from `ignore` to `enable-extensions`. The description shows the flake8 failure from the naive placement and the clean output after, the lint and test results per interpreter, and the line proving the package is gone from the environment the tests ran in.

The reviewer checks that no file under `orquesta/specs/mock` or `orquesta/composers` was touched, since those are product code that only share the name, and that the entry point in `setup.py` is unchanged. They read the per-version results rather than one summary line, because a mock-related difference would show on 3.12 first. If the search for assertion look-alikes finds something, it is listed as its own section with the test's name, so it can be fixed in this pull request or split out.

## Run it on every GitHub issue labelled tech-debt

Backports outlive the interpreters they were written for, and removing one is the sort of issue that sits in a backlog for a year. Add an automation to the Project with a `github` trigger on `issues.labeled` and your label in its `labels` setting, and save the prompt above. When a repository owner, member or collaborator adds the label, a run starts, and the event is placed after the prompt as third-party data.

Because the prompt names the package, this automation does one job. For a general version, change its first sentence to ask for whichever backport the issue names, and keep the rest: the check that Python 2 is gone, the lint rule and the per-version test run apply to `mock`, `typing` and `enum34` alike. A label applied by a bot never starts a run.

## Why run it on Rush?

A one-line import change is easy to make and easy to get subtly wrong three ways: in the wrong position for the linter, on one interpreter only, or with the package still installed so the old import would have kept working anyway. The run checks all three in its own sandbox, with three Python versions installed and the dependency removed, and the output of every command is kept with the session.

It also turns the change into a rule. Enabling `H216` is the difference between cleaning up once and never having to again, and the run shows the rule passing on the whole package before the pull request asks anyone to trust it. A reviewer gets a diff of a few lines and the evidence for each of them.

## Frequently asked questions

### Is unittest.mock the same as the mock package?

They are the same code at different ages. `mock` is a rolling backport of the standard library module, so `mock` 4.0.3 matches the standard library of the Python version it was cut from, and your interpreter's own copy may be newer. `patch`, `MagicMock`, `call` and `ANY` have the same names in both.

### Can I mix both in one test suite during the migration?

It works but invites confusion: `mock.Mock` and `unittest.mock.Mock` are different classes, so an `isinstance` check against one fails for objects made by the other. The agent converts every import in one pull request and removes the package, which leaves no mixed state.

### What if my project still supports Python 2?

Then the backport is doing its job and should stay, usually behind a `try` and `except ImportError` pair. The prompt has the agent read the supported versions first and stop with a report if Python 2 is among them. Dropping Python 2 is a separate decision with its own pull request.

### Why did a test start failing on Python 3.12 after the switch?

Most likely it read an attribute such as `called_once_with` from a mock without the `assert_` prefix. Python 3.12's `unittest.mock` raises `AttributeError` for those names, while older versions and the 4.0.3 backport returned a new mock, so the line passed without checking anything. The failure is the test telling you it never asserted.

## More jobs like this: Upgrade dependencies weekly

- [Migrate From mysql to mysql2 in a Node.js App](https://getrush.ai/run/migrate-mysql-to-mysql2/mysql/)
- [Migrate from node-sass to Dart Sass in a Webpack Project](https://getrush.ai/run/migrate-node-sass-to-dart-sass/webpack/)
- [Migrate a Python Project From oauth2client to google-auth](https://getrush.ai/run/migrate-oauth2client-to-google-auth/oauth2client/)
- [Migrate From packr to Go's embed Package](https://getrush.ai/run/migrate-packr-to-embed/packr/)
- [Replace pkg/errors With the Standard Library in a Go Module](https://getrush.ai/run/migrate-pkg-errors-to-stdlib-errors/pkg-errors/)
- [Fix "No module named 'pkg_resources'" by Migrating to importlib.resources](https://getrush.ai/run/migrate-pkg-resources-to-importlib-resources/setuptools/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
