Testing Dependencies with Overrides

Warning

The current page still doesn’t have a translation for this language.

But you can help translating it: Contributing.

Overriding dependencies during testing

There are some scenarios where you might want to override a dependency during testing.

You don’t want the original dependency to run (nor any of the sub-dependencies it might have).

Instead, you want to provide a different dependency that will be used only during tests (possibly only some specific tests), and will provide a value that can be used where the value of the original dependency was used.

Use cases: external service

An example could be that you have an external authentication provider that you need to call.

You send it a token and it returns an authenticated user.

This provider might be charging you per request, and calling it might take some extra time than if you had a fixed mock user for tests.

You probably want to test the external provider once, but not necessarily call it for every test that runs.

In this case, you can override the dependency that calls that provider, and use a custom dependency that returns a mock user, only for your tests.

Use the app.dependency_overrides attribute

For these cases, your FastAPI application has an attribute app.dependency_overrides, it is a simple dict.

To override a dependency for testing, you put as a key the original dependency (a function), and as the value, your dependency override (another function).

And then FastAPI will call that override instead of the original dependency.

Python 3.9+Python 3.6+Python 3.10+ non-AnnotatedPython 3.6+ non-Annotated

  1. from typing import Annotated
  3. from fastapi import Depends, FastAPI
  4. from fastapi.testclient import TestClient
  6. app = FastAPI()
  9. async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
  10.     return {"q": q, "skip": skip, "limit": limit}
  13. @app.get("/items/")
  14. async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
  15.     return {"message": "Hello Items!", "params": commons}
  18. @app.get("/users/")
  19. async def read_users(commons: Annotated[dict, Depends(common_parameters)]):
  20.     return {"message": "Hello Users!", "params": commons}
  23. client = TestClient(app)
  26. async def override_dependency(q: str | None = None):
  27.     return {"q": q, "skip": 5, "limit": 10}
  30. app.dependency_overrides[common_parameters] = override_dependency
  33. def test_override_in_items():
  34.     response = client.get("/items/")
  35.     assert response.status_code == 200
  36.     assert response.json() == {
  37.         "message": "Hello Items!",
  38.         "params": {"q": None, "skip": 5, "limit": 10},
  39.     }
  42. def test_override_in_items_with_q():
  43.     response = client.get("/items/?q=foo")
  44.     assert response.status_code == 200
  45.     assert response.json() == {
  46.         "message": "Hello Items!",
  47.         "params": {"q": "foo", "skip": 5, "limit": 10},
  48.     }
  51. def test_override_in_items_with_params():
  52.     response = client.get("/items/?q=foo&skip=100&limit=200")
  53.     assert response.status_code == 200
  54.     assert response.json() == {
  55.         "message": "Hello Items!",
  56.         "params": {"q": "foo", "skip": 5, "limit": 10},
  57.     }
  1. from typing import Annotated, Union
  3. from fastapi import Depends, FastAPI
  4. from fastapi.testclient import TestClient
  6. app = FastAPI()
  9. async def common_parameters(
  10.     q: Union[str, None] = None, skip: int = 0, limit: int = 100
  11. ):
  12.     return {"q": q, "skip": skip, "limit": limit}
  15. @app.get("/items/")
  16. async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
  17.     return {"message": "Hello Items!", "params": commons}
  20. @app.get("/users/")
  21. async def read_users(commons: Annotated[dict, Depends(common_parameters)]):
  22.     return {"message": "Hello Users!", "params": commons}
  25. client = TestClient(app)
  28. async def override_dependency(q: Union[str, None] = None):
  29.     return {"q": q, "skip": 5, "limit": 10}
  32. app.dependency_overrides[common_parameters] = override_dependency
  35. def test_override_in_items():
  36.     response = client.get("/items/")
  37.     assert response.status_code == 200
  38.     assert response.json() == {
  39.         "message": "Hello Items!",
  40.         "params": {"q": None, "skip": 5, "limit": 10},
  41.     }
  44. def test_override_in_items_with_q():
  45.     response = client.get("/items/?q=foo")
  46.     assert response.status_code == 200
  47.     assert response.json() == {
  48.         "message": "Hello Items!",
  49.         "params": {"q": "foo", "skip": 5, "limit": 10},
  50.     }
  53. def test_override_in_items_with_params():
  54.     response = client.get("/items/?q=foo&skip=100&limit=200")
  55.     assert response.status_code == 200
  56.     assert response.json() == {
  57.         "message": "Hello Items!",
  58.         "params": {"q": "foo", "skip": 5, "limit": 10},
  59.     }
  1. from typing import Union
  3. from fastapi import Depends, FastAPI
  4. from fastapi.testclient import TestClient
  5. from typing_extensions import Annotated
  7. app = FastAPI()
  10. async def common_parameters(
  11.     q: Union[str, None] = None, skip: int = 0, limit: int = 100
  12. ):
  13.     return {"q": q, "skip": skip, "limit": limit}
  16. @app.get("/items/")
  17. async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
  18.     return {"message": "Hello Items!", "params": commons}
  21. @app.get("/users/")
  22. async def read_users(commons: Annotated[dict, Depends(common_parameters)]):
  23.     return {"message": "Hello Users!", "params": commons}
  26. client = TestClient(app)
  29. async def override_dependency(q: Union[str, None] = None):
  30.     return {"q": q, "skip": 5, "limit": 10}
  33. app.dependency_overrides[common_parameters] = override_dependency
  36. def test_override_in_items():
  37.     response = client.get("/items/")
  38.     assert response.status_code == 200
  39.     assert response.json() == {
  40.         "message": "Hello Items!",
  41.         "params": {"q": None, "skip": 5, "limit": 10},
  42.     }
  45. def test_override_in_items_with_q():
  46.     response = client.get("/items/?q=foo")
  47.     assert response.status_code == 200
  48.     assert response.json() == {
  49.         "message": "Hello Items!",
  50.         "params": {"q": "foo", "skip": 5, "limit": 10},
  51.     }
  54. def test_override_in_items_with_params():
  55.     response = client.get("/items/?q=foo&skip=100&limit=200")
  56.     assert response.status_code == 200
  57.     assert response.json() == {
  58.         "message": "Hello Items!",
  59.         "params": {"q": "foo", "skip": 5, "limit": 10},
  60.     }

Tip

Prefer to use the Annotated version if possible.

  1. from fastapi import Depends, FastAPI
  2. from fastapi.testclient import TestClient
  4. app = FastAPI()
  7. async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
  8.     return {"q": q, "skip": skip, "limit": limit}
  11. @app.get("/items/")
  12. async def read_items(commons: dict = Depends(common_parameters)):
  13.     return {"message": "Hello Items!", "params": commons}
  16. @app.get("/users/")
  17. async def read_users(commons: dict = Depends(common_parameters)):
  18.     return {"message": "Hello Users!", "params": commons}
  21. client = TestClient(app)
  24. async def override_dependency(q: str | None = None):
  25.     return {"q": q, "skip": 5, "limit": 10}
  28. app.dependency_overrides[common_parameters] = override_dependency
  31. def test_override_in_items():
  32.     response = client.get("/items/")
  33.     assert response.status_code == 200
  34.     assert response.json() == {
  35.         "message": "Hello Items!",
  36.         "params": {"q": None, "skip": 5, "limit": 10},
  37.     }
  40. def test_override_in_items_with_q():
  41.     response = client.get("/items/?q=foo")
  42.     assert response.status_code == 200
  43.     assert response.json() == {
  44.         "message": "Hello Items!",
  45.         "params": {"q": "foo", "skip": 5, "limit": 10},
  46.     }
  49. def test_override_in_items_with_params():
  50.     response = client.get("/items/?q=foo&skip=100&limit=200")
  51.     assert response.status_code == 200
  52.     assert response.json() == {
  53.         "message": "Hello Items!",
  54.         "params": {"q": "foo", "skip": 5, "limit": 10},
  55.     }

Tip

Prefer to use the Annotated version if possible.

  1. from typing import Union
  3. from fastapi import Depends, FastAPI
  4. from fastapi.testclient import TestClient
  6. app = FastAPI()
  9. async def common_parameters(
  10.     q: Union[str, None] = None, skip: int = 0, limit: int = 100
  11. ):
  12.     return {"q": q, "skip": skip, "limit": limit}
  15. @app.get("/items/")
  16. async def read_items(commons: dict = Depends(common_parameters)):
  17.     return {"message": "Hello Items!", "params": commons}
  20. @app.get("/users/")
  21. async def read_users(commons: dict = Depends(common_parameters)):
  22.     return {"message": "Hello Users!", "params": commons}
  25. client = TestClient(app)
  28. async def override_dependency(q: Union[str, None] = None):
  29.     return {"q": q, "skip": 5, "limit": 10}
  32. app.dependency_overrides[common_parameters] = override_dependency
  35. def test_override_in_items():
  36.     response = client.get("/items/")
  37.     assert response.status_code == 200
  38.     assert response.json() == {
  39.         "message": "Hello Items!",
  40.         "params": {"q": None, "skip": 5, "limit": 10},
  41.     }
  44. def test_override_in_items_with_q():
  45.     response = client.get("/items/?q=foo")
  46.     assert response.status_code == 200
  47.     assert response.json() == {
  48.         "message": "Hello Items!",
  49.         "params": {"q": "foo", "skip": 5, "limit": 10},
  50.     }
  53. def test_override_in_items_with_params():
  54.     response = client.get("/items/?q=foo&skip=100&limit=200")
  55.     assert response.status_code == 200
  56.     assert response.json() == {
  57.         "message": "Hello Items!",
  58.         "params": {"q": "foo", "skip": 5, "limit": 10},
  59.     }

Tip

You can set a dependency override for a dependency used anywhere in your FastAPI application.

The original dependency could be used in a path operation function, a path operation decorator (when you don’t use the return value), a .include_router() call, etc.

FastAPI will still be able to override it.

Then you can reset your overrides (remove them) by setting app.dependency_overrides to be an empty dict:

  1. app.dependency_overrides = {}

Tip

If you want to override a dependency only during some tests, you can set the override at the beginning of the test (inside the test function) and reset it at the end (at the end of the test function).