{"id":34685835,"url":"https://github.com/alixlahuec/fastapi-checks","last_synced_at":"2026-04-24T04:33:23.549Z","repository":{"id":214396298,"uuid":"735793596","full_name":"alixlahuec/fastapi-checks","owner":"alixlahuec","description":"Utility package to run checks against FastAPI applications","archived":false,"fork":false,"pushed_at":"2024-01-28T01:20:54.000Z","size":71,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-13T00:46:37.364Z","etag":null,"topics":["cli","fastapi","pytest-plugin","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alixlahuec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-12-26T05:16:15.000Z","updated_at":"2024-01-23T15:06:30.000Z","dependencies_parsed_at":"2023-12-27T22:45:02.410Z","dependency_job_id":"1ba5fd31-9f97-4a82-b219-a2baefa87471","html_url":"https://github.com/alixlahuec/fastapi-checks","commit_stats":null,"previous_names":["alixlahuec/fastapi-checks"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/alixlahuec/fastapi-checks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alixlahuec%2Ffastapi-checks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alixlahuec%2Ffastapi-checks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alixlahuec%2Ffastapi-checks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alixlahuec%2Ffastapi-checks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alixlahuec","download_url":"https://codeload.github.com/alixlahuec/fastapi-checks/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alixlahuec%2Ffastapi-checks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32209893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","fastapi","pytest-plugin","python"],"created_at":"2025-12-24T21:47:18.547Z","updated_at":"2026-04-24T04:33:23.544Z","avatar_url":"https://github.com/alixlahuec.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"A small library that provides tooling to inspect and run tests against [FastAPI](https://github.com/tiangolo/fastapi) applications.\n\n[![codecov](https://codecov.io/github/alixlahuec/fastapi-checks/graph/badge.svg?token=CvAhnsWNf9)](https://codecov.io/github/alixlahuec/fastapi-checks)\n\n## Installation\n\n```bash\npoetry add fastapi-checks # with poetry\npip install fastapi-checks # with pip\n```\n\n### For CLI usage\n\n```bash\npoetry add fastapi-checks --extras \"cli\" # with poetry\npip install fastapi-checks[cli] # with pip\n```\n\n## Usage\n\n### CLI\n\n#### General options\n\n| Parameter | Description |\n| --------- | ----------- |\n| `--app` | (Required) The location of the FastAPI instance to use. Must be provided before any commands. |\n| `--config` | (Optional) The location of the config file to use. Must be provided before any commands |\n\n```bash\nfastapi-checks --app \"app_example.main:app\" routes\nfastapi-checks --config \"myconfigfile.json\" debug\n```\n\n#### Using a config file\n\nThe library uses [`pycosmiconfig`](https://github.com/JuroOravec/pycosmiconfig/) to automatically detect and load configuration files.\nAmong other formats, it supports the following:\n- a `[tool.fastapi_checks]` property in pyproject.toml\n- a `fastapi_checks.json`, `fastapi_checks.yaml`, `fastapi_checks.toml` file inside a `.config` subdirectory\n- a `fastapi_checks.config.py` file\n\nSee the project's homepage for the full list of supported formats.\n\n#### Available commands\n\n**`routes`**\n\nView a summary of API routes. Available options:\n- `--html`: render the results as an interactive table in the browser (uses [Dash](https://dash.plotly.com/)).\n- `--match`: only show routes whose path matches a specific pattern.\n   + This will be parsed as a regular expression (e.g., `--match \"0.1\"` will return all routes whose path includes `\"0.1\"`; `--match \"^/0.1\"` will return all routes whose path starts with `\"/0.1\"`).\n\n```bash\nfastapi-checks routes\nfastapi-checks routes --html\nfastapi-checks routes --match \"0.1\"\n```\n\n**`debug`**\n\nShow debug information (e.g. config file, FastAPI application details).\n\n```bash\nfastapi-checks debug\n```\n\n### Test runners\n\nThe library can also be used to write tests asserting against a FastAPI application.\n\nAn example (using Pytest):\n\n```python\nfrom fastapi_checks.testing import FastApiChecks\nfrom pytest import mark\n\nfrom app_example.main import app  # the FastAPI app to assert against\n\n\n# This is an alias for the App parser\nFAC = FastApiChecks(app=app)\n\n\n# Are all routes under /0.1 marked as deprecated?\n@mark.parametrize(\n    \"api_route\",\n    FAC.api_routes(path_regex=\"^/0.1\"),\n)\ndef test_01_routes_are_deprecated(api_route):\n    assert api_route.route.deprecated is True\n\n\n# Are all generated operation IDs unique?\ndef test_unique_operation_ids():\n    ids = [r.operation_id for r in FAC.api_routes()]\n    ids_set = set(ids)\n\n    assert len(ids_set) == len(ids)\n```\n\nFor Pytest users, the library also exposes a `fastapi_checks` fixture. It requires declaring a fixture called `fastapi_app`, which should return a FastAPI instance.\nThe `fastapi_checks` fixture will return the equivalent of `FastApiChecks(app=fastapi_app)` from the example above.\n\n```python\nfrom pytest import fixture\n\n\n@fixture\ndef fastapi_app():\n    from app_example.main import app  # the FastAPI app to assert against\n    return app\n\n\ndef test_01_routes_are_deprecated(fastapi_checks):\n    routes = fastapi_checks.api_routes(path_regex=\"0.1\")\n\n    for r in routes:\n        assert len(r.security) \u003e 0\n```\n\n## Concepts\n\nThe library's core functionalities are exposed through a few Pydantic models, which can be used to interact with FastAPI concepts (e.g. dependencies, routes). Each model exposes some useful methods, as well as the original object where applicable.\n\n### `App`\n\nWraps `fastapi.FastAPI`. The original FastAPI instance is available under the `app` property.\n\n```python\nfrom fastapi_checks.models import App\nfrom app_example.main import app\n\n\napp_instance = App(app=app)\n\n# Get the original FastAPI object\n# A lot of data is directly available, through methods like .openapi()\n# See the FastAPI documentation for more information\napp_instance.app\n\n# Get all API routes\n# They are returned as ApiRoute instances\napp_instance.api_routes()\n\n# Get all API routes that match a RegExp\napp_instance.api_routes(path_regex=\"^/0.1\")\n\n# Get all dependencies (recursively), by route path\n# They are returned as Dependency instances\napp_instance.dependencies()\n\n# Get all dependencies (recursively), for API routes that match a RegExp\napp_instance.dependencies(path_regex=\"^/0.1\")\n```\n\n### `ApiRoute`\n\nWraps `fastapi.routing.APIRoute`. The original APIRoute instance is available under the `route` property.\n\n```python\nfrom fastapi_checks.models import App\nfrom app_example.main import app\n\n\napp_instance = App(app=app)\n\napi_route = app_instance.api_routes()[0]\n\n# Get the original APIRoute object\napi_route.route\n\n# Get the generated OpenAPI spec for the route\napi_route.openapi\n\n# Get the route's operation ID\napi_route.operation_id\n\n# Get all dependencies (recursively)\napi_route.dependencies\n\n# Get all unique dependencies (recursively)\n# This filters out dependencies on the same callable\napi_route.unique_dependencies\n\n# Get the names of all (unique) dependencies (recursively)\n# Each value will be either a method name or a class name\napi_route.dependency_names\n\n# Get all Mark instances attached to the route's (unique) dependencies\napi_route.dependency_marks\n\n# Get the security requirements for the route\n# At the moment, only the HTTPBearer scheme is supported\napi_route.security()\napi_route.security(scheme=\"HTTPBearer\")\n\n# Check if the route's patch matches a RegExp\n# This is used internally in App.api_routes() or App.dependencies()\napi_route.predicate(path_regex=\"^/0.1\")\n```\n\n### `Dependency`\n\nWraps `fastapi.Depends`. The original callable is available under the `callable` property.\n\n```python\nfrom fastapi_checks.models import App\nfrom app_example.main import app\n\n\napp_instance = App(app=app)\n\napi_route = app_instance.api_routes()[0]\ndependency = api_route.dependencies()[0]\n\n# Get the callable\ndependency.callable\n\n# Get the name of the callable\n# This is used internally in ApiRoute.dependency_names()\ndependency.humanized\n\n# Get the name of the argument where the dependency is injected, if applicable\n# For app-, router-, and route-level dependencies, this will be null\ndependency.argname\n\n# Get the route associated with the dependency\n# assert dependency.route == api_route\ndependency.route\n\n# Get the context in which the dependency is called (directly or through nested dependencies)\n# This will be either:\n# - \"path\", for app-, router-, and route-level dependencies\n# - \"handler\", for route handler dependencies\ndependency.origin\n\n# Get the Mark instance attached to the dependency, if it exists\n# This is used internally in ApiRoute.dependency_marks()\ndependency.mark\n\n# Check if the dependency has / doesn't have certain tags\n# NB: the tags must have been provided using the `mark` decorator\ndependency.tags_include_all(tags=[\"tag1\", \"tag2\"])\ndependency.tags_exclude_all(tags=[\"tag3\", \"tag4\"])\ndependency.tags_include(tags=[\"tag1\", \"tag3\"])\n```\n\n### `Mark`\n\nThis model facilitates working with dependencies; it doesn't map to a FastAPI concept. It enables adding markup to callables being used as FastAPI dependencies, to help answer questions like \"How many endpoints rely on a dependency with [tag]?\". `Mark` annotations should be created using the `mark` decorator, and are available on `Dependency` objects.\n\n**Decorator usage:**\n\n```python\n# app_example/services/auth.py\nfrom fastapi_checks.decorators import mark\n\n\n@mark(\"auth\")\ndef some_auth_dependency():\n    pass\n\n\n@mark(\"auth\")\nclass AnotherAuthDependency:\n    def __init__(*args, **kwargs):\n        ...\n    def __call__(*args, **kwargs):\n        ...\n```\n\n**Assertions on Mark instances:**\n\n```python\n# tests/app.py\nfrom fastapi_checks.testing import FastApiChecks\nfrom app_example.main import app\n\n\nFAC = FastApiChecks(app=app)\n\n\ndef test_all_routes_use_auth():\n    api_routes = FAC.api_routes()\n    for r in api_routes:\n        assert r.dependency_marks.includes(\"auth\"), f\"{r.route.path} uses an auth dependency\"\n```\n\n**Model properties:**\n\n```python\nfrom fastapi_checks.models import App\nfrom app_example.main import app\n\n\napp_instance = App(app=app)\n\napi_route = app_instance.api_routes()[0]\ndependency = api_route.dependencies()[0]\nmark = dependency.mark\n\n# Get the \"marked\" callable\nmark.marked\n\n# Get the tags attached to the callable\nmark.tags\n```\n\n## Development\n\n- Clone the repository\n- Install dependencies with `poetry install`\n- The following commands are available:\n   + `make fixes`: lint files with Ruff\n   + `make checks`: check files with Ruff\n   + `make typecheck`: typecheck files with mypy\n   + `make test`: run tests with Pytest\n   + `make test:cov`: run tests with Pytest \u0026 report on coverage\n\nFor rapid development, you can run CLI commands against the sample FastAPI application located in `app_example`. In the root directory:\n\n```bash\npoetry run fastapi-checks routes\n```\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falixlahuec%2Ffastapi-checks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falixlahuec%2Ffastapi-checks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falixlahuec%2Ffastapi-checks/lists"}