diff --git a/CHANGELOG.md b/CHANGELOG.md index eaaa0df0..114aeebd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,7 @@ This project uses famous football coaches as release codenames, following an A-Z - ADR-0011: Use Coach-Themed Semantic Versioning - ADR-0012: Adopt AI-Assisted Development Workflow - ADR-0013: Adopt Spec-Driven Development (SDD) +- ADR-0014: Unit and Integration Test Strategy (supersedes ADR-0007) (#490) - `.claude/skills/create-issue/SKILL.md` and `.claude/skills/add-endpoint/SKILL.md`: extracted from `CLAUDE.md` as on-demand skills, so the SDD issue templates and the endpoint/schema-change recipes load only when invoked instead of every diff --git a/CLAUDE.md b/CLAUDE.md index 5900f60b..12b24814 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,8 +42,11 @@ used by the Docker entrypoint. (not 422 — it is a semantic error, not a validation failure) - **Logging**: `logging` module only; never `print()` - **Tests**: integration tests against the real SQLite DB (seeded via - Alembic migrations) via `TestClient` — no mocking. Naming pattern - `test_request_{method}_{resource}_{context}_response_{outcome}`; + Alembic migrations) via `TestClient` — no mocking. Unit tests in + `tests/unit/` isolate dependencies with mocks and do not require database + migrations (see ADR-0014). Naming pattern + `test_request_{method}_{resource}_{context}_response_{outcome}` (routes); + `test_{function}_{context}_returns_{outcome}` (service unit tests); docstrings single-line, concise; `tests/player_fake.py` for test data; `tests/conftest.py` provides a `function`-scoped `client` fixture for isolation; `tests/test_main.py` excluded from Black; @@ -107,6 +110,8 @@ a release tag with a coach name not in that table. docstring updates that don't change the API contract) - Tests in `tests/` — maintain async patterns, naming convention, and integration-test approach (no mocking) +- Tests in `tests/unit/` — maintain async patterns, naming convention, and + unit-test isolation (mock dependencies as needed) - Documentation and docstring updates - Lint/format fixes - Refactoring within existing architectural patterns @@ -160,6 +165,6 @@ confirms. ## Architecture Decision Records -Significant architectural decisions are documented in `docs/adr/` (ADR-0001–0013). +Significant architectural decisions are documented in `docs/adr/` (ADR-0001–0014). Load these before proposing structural changes. When a proposal would change an accepted decision, create a new ADR rather than editing the existing one. diff --git a/docs/adr/0007-integration-only-test-strategy.md b/docs/adr/0007-integration-only-test-strategy.md index 76f08ed0..6f822f7d 100644 --- a/docs/adr/0007-integration-only-test-strategy.md +++ b/docs/adr/0007-integration-only-test-strategy.md @@ -4,8 +4,7 @@ Date: 2026-03-21 ## Status -Accepted. Unit tests with mocking for the service and route layers are -under consideration — tracked in issue #490. +Superseded by [ADR-0014](0014-unit-and-integration-test-strategy.md). ## Context diff --git a/docs/adr/0014-unit-and-integration-test-strategy.md b/docs/adr/0014-unit-and-integration-test-strategy.md new file mode 100644 index 00000000..d1bcb341 --- /dev/null +++ b/docs/adr/0014-unit-and-integration-test-strategy.md @@ -0,0 +1,99 @@ +# ADR-0014: Unit and Integration Test Strategy + +Date: 2026-10-26 + +## Status + +Accepted. Supersedes [ADR-0007](0007-integration-only-test-strategy.md). + +## Context + +ADR-0007 established integration tests only: every test exercises the +full stack via `TestClient` against the real SQLite database, with no +mocking. Its consequences already flagged two gaps, tracked in issue +#490: + +- **Unreachable error paths** — the `SQLAlchemyError` handlers in + `services/player_service.py` and the HTTP 500 branches in + `routes/player_route.py` cannot be triggered against a healthy + SQLite database. They are excluded from coverage with + `# pragma: no cover`, so the reported coverage says nothing about + them. +- **No layer isolation** — an integration test failure does not + pinpoint whether the route, the service, or the database is at + fault. + +`unittest.mock.AsyncMock` with `spec=AsyncSession` produces a mock +whose async methods (`commit`, `refresh`, `execute`, `delete`) are +awaitable and whose sync methods (`add`) are not, matching the real +`AsyncSession` interface. Route functions are plain `async def` +callables and can be invoked directly with their dependencies passed +as arguments, bypassing FastAPI's dependency injection. + +## Alternatives Considered + +- **Keep integration-only (ADR-0007)** — the error paths stay + untested and excluded from coverage. Simulating database failures + against SQLite (corrupting the file, revoking permissions) is + fragile and platform-dependent. +- **Fault injection via dependency overrides** — override + `generate_async_session` in `TestClient` with a session that raises + on `commit`. This covers the error paths through HTTP but couples + the tests to the full stack anyway and still offers no layer + isolation. +- **Replace integration tests with unit tests** — fast and isolated, + but mocks can silently diverge from real behavior; ADR-0007's + argument for exercising the real database still holds for the happy + paths and the HTTP contract. + +## Decision + +We will maintain two test tiers: + +- **Integration tests** in `tests/` (`test_main.py`, + `test_migrations.py`) remain the authority for the API contract: + status codes, headers, response shapes, and real database + behavior. No mocking. +- **Unit tests** in `tests/unit/` test the route and service layers in + isolation. Service tests mock `AsyncSession` + (`AsyncMock(spec=AsyncSession)`); route tests mock the + `player_service` functions and the cache. Unit tests do not apply + Alembic migrations (`tests/unit/conftest.py` overrides the + session-scoped `apply_migrations` fixture). + +Naming conventions: + +- Route unit tests follow the integration pattern + `test_request_{method}_{resource}_{context}_response_{outcome}`, + since they verify the same HTTP-level outcomes. +- Service unit tests use `test_{function}_{context}_returns_{outcome}` + (e.g. `test_create_async_commit_error_returns_none`), since there is + no HTTP request involved. + +Error branches covered by unit tests must not carry +`# pragma: no cover`; the marker is reserved for code that no test +tier can reach. + +This keeps the integration suite as the source of truth for +observable behavior while giving the error paths real, counted +coverage. + +## Consequences + +**Positive:** + +- Error-handling paths (rollback on `SQLAlchemyError`, HTTP 500 + responses) are exercised and counted in coverage. +- Unit test failures pinpoint the failing layer. +- Unit tests need no database or migrations and run fast. + +**Negative:** + +- Mocks encode assumptions about `AsyncSession` and the service API; + if either changes, unit tests may keep passing while integration + tests fail, or the reverse. Both tiers must be updated together. +- Two naming conventions and two fixture setups to maintain. +- Route unit tests call route functions directly, so they do not + verify FastAPI wiring (path parameters, dependency injection, + response model serialization). That remains the integration suite's + job. diff --git a/docs/adr/README.md b/docs/adr/README.md index 9698d64d..9dba59b4 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -18,10 +18,11 @@ one and the three-part test. | [0004](0004-squad-number-as-mutation-key.md) | Squad Number as the Mutation Key | Accepted | 2026-03-21 | | [0005](0005-full-replace-put-no-patch.md) | Full Replace PUT, No PATCH | Accepted | 2026-03-21 | | [0006](0006-in-memory-caching-with-aiocache.md) | In-Memory Caching with aiocache | Accepted | 2026-03-21 | -| [0007](0007-integration-only-test-strategy.md) | Integration-Only Test Strategy | Accepted | 2026-03-21 | +| [0007](0007-integration-only-test-strategy.md) | Integration-Only Test Strategy | Superseded | 2026-03-21 | | [0008](0008-layered-architecture.md) | Layered Architecture with FastAPI Dependency Injection | Accepted | 2026-04-02 | | [0009](0009-docker-and-compose-strategy.md) | Docker and Compose Strategy | Accepted | 2026-04-02 | | [0010](0010-alembic-migration-based-schema-management.md) | Alembic Migration-Based Schema Management | Accepted | 2026-04-09 | | [0011](0011-coach-themed-versioning.md) | Use Coach-Themed Semantic Versioning | Accepted | 2026-06-10 | | [0012](0012-ai-assisted-development-workflow.md) | Adopt AI-Assisted Development Workflow | Accepted | 2026-06-10 | | [0013](0013-spec-driven-development.md) | Adopt Spec-Driven Development (SDD) | Accepted | 2026-06-10 | +| [0014](0014-unit-and-integration-test-strategy.md) | Unit and Integration Test Strategy | Accepted | 2026-10-26 | diff --git a/tests/unit/conftest.py b/tests/unit/conftest.py new file mode 100644 index 00000000..0abff63d --- /dev/null +++ b/tests/unit/conftest.py @@ -0,0 +1,11 @@ +""" +Fixtures for the unit tests. +""" + +import pytest + + +@pytest.fixture(scope="session", autouse=True) +def apply_migrations(): + """Disable database migrations for unit tests.""" + pass diff --git a/tests/unit/test_player_route.py b/tests/unit/test_player_route.py new file mode 100644 index 00000000..0d57c558 --- /dev/null +++ b/tests/unit/test_player_route.py @@ -0,0 +1,617 @@ +""" +Unit tests for the Player API routes. +""" + +from unittest.mock import AsyncMock, patch +from uuid import UUID + +import pytest +from fastapi import HTTPException, Response, status +from sqlalchemy.ext.asyncio import AsyncSession + +from models.player_model import PlayerRequestModel +from routes.player_route import ( + CACHE_KEY, + CACHE_TTL, + delete_async, + get_all_async, + get_by_id_async, + get_by_squad_number_async, + post_async, + put_async, + simple_memory_cache, +) +from schemas.player_schema import Player + + +@pytest.fixture +def existing_player_schema(): + return Player( + id=UUID("01772c59-43f0-5d85-b913-c78e4e281452"), + first_name="Damián", + middle_name="Emiliano", + last_name="Martínez", + date_of_birth="1992-09-02T00:00:00.000Z", + squad_number=23, + position="Goalkeeper", + abbr_position="GK", + team="Aston Villa FC", + league="Premier League", + starting11=True, + ) + + +@pytest.fixture +def player_request_model(): + return PlayerRequestModel( + first_name="Giovani", + last_name="Lo Celso", + date_of_birth="1996-07-09T00:00:00.000Z", + squad_number=27, + position="Central Midfield", + abbr_position="CM", + team="Real Betis Balompié", + league="La Liga", + starting11=False, + ) + + +@pytest.fixture +def player_schema(): + return Player( + first_name="Giovani", + last_name="Lo Celso", + date_of_birth="1996-07-09T00:00:00.000Z", + squad_number=27, + position="Central Midfield", + abbr_position="CM", + team="Real Betis Balompié", + league="La Liga", + starting11=False, + ) + + +@pytest.mark.anyio +async def test_request_post_player_body_nonexistent_response_created( + player_request_model, player_schema +): + """Create a player when the squad number does not already exist.""" + mock_async_session = AsyncMock(spec=AsyncSession) + response = Response() + + with ( + patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve, + patch( + "routes.player_route.player_service.create_async", + new_callable=AsyncMock, + ) as mock_create, + patch.object( + simple_memory_cache, "clear", new_callable=AsyncMock + ) as mock_clear_cache, + ): + mock_retrieve.return_value = None + mock_create.return_value = player_schema + + result = await post_async( + player_model=player_request_model, + async_session=mock_async_session, + response=response, + ) + + assert result == player_schema + mock_retrieve.assert_awaited_once_with( + mock_async_session, player_request_model.squad_number + ) + mock_create.assert_awaited_once_with(mock_async_session, player_request_model) + assert ( + response.headers["Location"] + == f"/players/squadnumber/{player_request_model.squad_number}" + ) + mock_clear_cache.assert_awaited_once_with(CACHE_KEY) + + +@pytest.mark.anyio +async def test_request_post_player_body_existing_response_conflict( + player_request_model, player_schema +): + """Reject player creation when the squad number already exists.""" + mock_async_session = AsyncMock(spec=AsyncSession) + response = Response() + + with ( + patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve, + patch( + "routes.player_route.player_service.create_async", + new_callable=AsyncMock, + ) as mock_create, + patch.object( + simple_memory_cache, "clear", new_callable=AsyncMock + ) as mock_clear_cache, + ): + mock_retrieve.return_value = player_schema + + with pytest.raises(HTTPException) as exc_info: + await post_async( + player_model=player_request_model, + async_session=mock_async_session, + response=response, + ) + + assert exc_info.value.status_code == status.HTTP_409_CONFLICT + assert exc_info.value.detail == "A Player with this squad number already exists." + mock_retrieve.assert_awaited_once_with( + mock_async_session, player_request_model.squad_number + ) + mock_create.assert_not_awaited() + mock_clear_cache.assert_not_awaited() + + +@pytest.mark.anyio +async def test_request_post_player_body_service_failure_response_server_error( + player_request_model, +): + """Raise a server error when player creation fails.""" + mock_async_session = AsyncMock(spec=AsyncSession) + response = Response() + + with ( + patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve, + patch( + "routes.player_route.player_service.create_async", + new_callable=AsyncMock, + ) as mock_create, + patch.object( + simple_memory_cache, "clear", new_callable=AsyncMock + ) as mock_clear_cache, + ): + mock_retrieve.return_value = None + mock_create.return_value = None + + with pytest.raises(HTTPException) as exc_info: + await post_async( + player_model=player_request_model, + async_session=mock_async_session, + response=response, + ) + + assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR + assert ( + exc_info.value.detail == "Failed to create the Player due to a database error." + ) + mock_retrieve.assert_awaited_once_with( + mock_async_session, player_request_model.squad_number + ) + mock_create.assert_awaited_once_with(mock_async_session, player_request_model) + mock_clear_cache.assert_not_awaited() + + +@pytest.mark.anyio +async def test_request_get_players_cache_hit_response_success(player_schema): + """Return cached players without querying the service.""" + mock_async_session = AsyncMock(spec=AsyncSession) + response = Response() + + with ( + patch.object( + simple_memory_cache, "get", new_callable=AsyncMock + ) as mock_get_cache, + patch( + "routes.player_route.player_service.retrieve_all_async", + new_callable=AsyncMock, + ) as mock_retrieve_all, + ): + mock_get_cache.return_value = [player_schema] + + result = await get_all_async( + response=response, async_session=mock_async_session + ) + + assert result == [player_schema] + assert response.headers["X-Cache"] == "HIT" + mock_get_cache.assert_awaited_once_with(CACHE_KEY) + mock_retrieve_all.assert_not_awaited() + + +@pytest.mark.anyio +async def test_request_get_players_cache_miss_response_success(player_schema): + """Retrieve and cache players when the cache misses.""" + mock_async_session = AsyncMock(spec=AsyncSession) + response = Response() + + with ( + patch.object( + simple_memory_cache, "get", new_callable=AsyncMock + ) as mock_get_cache, + patch( + "routes.player_route.player_service.retrieve_all_async", + new_callable=AsyncMock, + ) as mock_retrieve_all, + patch.object( + simple_memory_cache, "set", new_callable=AsyncMock + ) as mock_set_cache, + ): + mock_get_cache.return_value = None + mock_retrieve_all.return_value = [player_schema] + + result = await get_all_async( + response=response, async_session=mock_async_session + ) + + assert result == [player_schema] + assert response.headers["X-Cache"] == "MISS" + mock_get_cache.assert_awaited_once_with(CACHE_KEY) + mock_retrieve_all.assert_awaited_once_with(mock_async_session) + mock_set_cache.assert_awaited_once_with(CACHE_KEY, [player_schema], ttl=CACHE_TTL) + + +@pytest.mark.anyio +async def test_request_get_player_id_existing_response_success(existing_player_schema): + """Return a player when the requested ID exists.""" + mock_async_session = AsyncMock(spec=AsyncSession) + + with patch( + "routes.player_route.player_service.retrieve_by_id_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_id: + mock_retrieve_by_id.return_value = existing_player_schema + + result = await get_by_id_async( + player_id=existing_player_schema.id, + async_session=mock_async_session, + ) + + assert result == existing_player_schema + mock_retrieve_by_id.assert_awaited_once_with( + mock_async_session, existing_player_schema.id + ) + + +@pytest.mark.anyio +async def test_request_get_player_id_unknown_response_not_found(): + """Raise not found when the requested ID does not exist.""" + mock_async_session = AsyncMock(spec=AsyncSession) + unknown_player_id = UUID("00000000-0000-0000-0000-000000000000") + + with patch( + "routes.player_route.player_service.retrieve_by_id_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_id: + mock_retrieve_by_id.return_value = None + + with pytest.raises(HTTPException) as exc_info: + await get_by_id_async( + player_id=unknown_player_id, + async_session=mock_async_session, + ) + + assert exc_info.value.status_code == status.HTTP_404_NOT_FOUND + mock_retrieve_by_id.assert_awaited_once_with(mock_async_session, unknown_player_id) + + +@pytest.mark.anyio +async def test_request_get_player_squadnumber_existing_response_success( + existing_player_schema, +): + """Return a player when the squad number exists.""" + mock_async_session = AsyncMock(spec=AsyncSession) + + with patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_squad_number: + mock_retrieve_by_squad_number.return_value = existing_player_schema + + result = await get_by_squad_number_async( + squad_number=existing_player_schema.squad_number, + async_session=mock_async_session, + ) + + assert result == existing_player_schema + mock_retrieve_by_squad_number.assert_awaited_once_with( + mock_async_session, existing_player_schema.squad_number + ) + + +@pytest.mark.anyio +async def test_request_get_player_squadnumber_unknown_response_not_found(): + """Raise not found when the squad number does not exist.""" + mock_async_session = AsyncMock(spec=AsyncSession) + unknown_squad_number = 99 + + with patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_squad_number: + mock_retrieve_by_squad_number.return_value = None + + with pytest.raises(HTTPException) as exc_info: + await get_by_squad_number_async( + squad_number=unknown_squad_number, + async_session=mock_async_session, + ) + + assert exc_info.value.status_code == status.HTTP_404_NOT_FOUND + mock_retrieve_by_squad_number.assert_awaited_once_with( + mock_async_session, unknown_squad_number + ) + + +@pytest.mark.anyio +async def test_request_put_player_squadnumber_existing_response_no_content( + existing_player_schema, player_request_model +): + """Update a player when the squad number matches.""" + player_request_model.squad_number = existing_player_schema.squad_number + mock_async_session = AsyncMock(spec=AsyncSession) + + with ( + patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_squad_number, + patch( + "routes.player_route.player_service.update_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_update, + patch.object( + simple_memory_cache, "clear", new_callable=AsyncMock + ) as mock_clear_cache, + ): + mock_retrieve_by_squad_number.return_value = existing_player_schema + mock_update.return_value = True + + result = await put_async( + squad_number=existing_player_schema.squad_number, + player_model=player_request_model, + async_session=mock_async_session, + ) + + assert result is None + mock_retrieve_by_squad_number.assert_awaited_once_with( + mock_async_session, existing_player_schema.squad_number + ) + mock_update.assert_awaited_once_with( + mock_async_session, existing_player_schema.squad_number, player_request_model + ) + mock_clear_cache.assert_awaited_once_with(CACHE_KEY) + + +@pytest.mark.anyio +async def test_request_put_player_squadnumber_mismatch_response_bad_request( + existing_player_schema, player_request_model +): + """Reject an update when the URL and body squad numbers differ.""" + player_request_model.squad_number = existing_player_schema.squad_number + 1 + mock_async_session = AsyncMock(spec=AsyncSession) + + with ( + patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_squad_number, + patch( + "routes.player_route.player_service.update_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_update, + patch.object( + simple_memory_cache, "clear", new_callable=AsyncMock + ) as mock_clear_cache, + ): + mock_retrieve_by_squad_number.return_value = existing_player_schema + + with pytest.raises(HTTPException) as exc_info: + await put_async( + squad_number=existing_player_schema.squad_number, + player_model=player_request_model, + async_session=mock_async_session, + ) + + assert exc_info.value.status_code == status.HTTP_400_BAD_REQUEST + mock_retrieve_by_squad_number.assert_not_awaited() + mock_update.assert_not_awaited() + mock_clear_cache.assert_not_awaited() + + +@pytest.mark.anyio +async def test_request_put_player_squadnumber_unknown_response_not_found( + player_request_model, +): + """Raise not found when the player does not exist.""" + mock_async_session = AsyncMock(spec=AsyncSession) + + with ( + patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_squad_number, + patch( + "routes.player_route.player_service.update_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_update, + patch.object( + simple_memory_cache, "clear", new_callable=AsyncMock + ) as mock_clear_cache, + ): + mock_retrieve_by_squad_number.return_value = None + + with pytest.raises(HTTPException) as exc_info: + await put_async( + squad_number=player_request_model.squad_number, + player_model=player_request_model, + async_session=mock_async_session, + ) + + assert exc_info.value.status_code == status.HTTP_404_NOT_FOUND + mock_retrieve_by_squad_number.assert_awaited_once_with( + mock_async_session, player_request_model.squad_number + ) + mock_update.assert_not_awaited() + mock_clear_cache.assert_not_awaited() + + +@pytest.mark.anyio +async def test_request_put_player_squadnumber_service_failure_response_server_error( + existing_player_schema, player_request_model +): + """Raise a server error when player update fails.""" + player_request_model.squad_number = existing_player_schema.squad_number + mock_async_session = AsyncMock(spec=AsyncSession) + + with ( + patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_squad_number, + patch( + "routes.player_route.player_service.update_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_update, + patch.object( + simple_memory_cache, "clear", new_callable=AsyncMock + ) as mock_clear_cache, + ): + mock_retrieve_by_squad_number.return_value = existing_player_schema + mock_update.return_value = False + + with pytest.raises(HTTPException) as exc_info: + await put_async( + squad_number=existing_player_schema.squad_number, + player_model=player_request_model, + async_session=mock_async_session, + ) + + assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR + assert ( + exc_info.value.detail == "Failed to update the Player due to a database error." + ) + mock_retrieve_by_squad_number.assert_awaited_once_with( + mock_async_session, existing_player_schema.squad_number + ) + mock_update.assert_awaited_once_with( + mock_async_session, existing_player_schema.squad_number, player_request_model + ) + mock_clear_cache.assert_not_awaited() + + +@pytest.mark.anyio +async def test_request_delete_player_squadnumber_existing_response_no_content( + existing_player_schema, +): + """Delete a player when the squad number exists.""" + mock_async_session = AsyncMock(spec=AsyncSession) + + with ( + patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_squad_number, + patch( + "routes.player_route.player_service.delete_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_delete, + patch.object( + simple_memory_cache, "clear", new_callable=AsyncMock + ) as mock_clear_cache, + ): + mock_retrieve_by_squad_number.return_value = existing_player_schema + mock_delete.return_value = True + + result = await delete_async( + squad_number=existing_player_schema.squad_number, + async_session=mock_async_session, + ) + + assert result is None + mock_retrieve_by_squad_number.assert_awaited_once_with( + mock_async_session, existing_player_schema.squad_number + ) + mock_delete.assert_awaited_once_with( + mock_async_session, existing_player_schema.squad_number + ) + mock_clear_cache.assert_awaited_once_with(CACHE_KEY) + + +@pytest.mark.anyio +async def test_request_delete_player_squadnumber_unknown_response_not_found(): + """Raise not found when the player does not exist.""" + mock_async_session = AsyncMock(spec=AsyncSession) + unknown_squad_number = 99 + + with ( + patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_squad_number, + patch( + "routes.player_route.player_service.delete_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_delete, + patch.object( + simple_memory_cache, "clear", new_callable=AsyncMock + ) as mock_clear_cache, + ): + mock_retrieve_by_squad_number.return_value = None + + with pytest.raises(HTTPException) as exc_info: + await delete_async( + squad_number=unknown_squad_number, + async_session=mock_async_session, + ) + + assert exc_info.value.status_code == status.HTTP_404_NOT_FOUND + mock_retrieve_by_squad_number.assert_awaited_once_with( + mock_async_session, unknown_squad_number + ) + mock_delete.assert_not_awaited() + mock_clear_cache.assert_not_awaited() + + +@pytest.mark.anyio +async def test_request_delete_player_squadnumber_service_failure_response_server_error( + existing_player_schema, +): + """Raise a server error when player deletion fails.""" + mock_async_session = AsyncMock(spec=AsyncSession) + + with ( + patch( + "routes.player_route.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve_by_squad_number, + patch( + "routes.player_route.player_service.delete_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_delete, + patch.object( + simple_memory_cache, "clear", new_callable=AsyncMock + ) as mock_clear_cache, + ): + mock_retrieve_by_squad_number.return_value = existing_player_schema + mock_delete.return_value = False + + with pytest.raises(HTTPException) as exc_info: + await delete_async( + squad_number=existing_player_schema.squad_number, + async_session=mock_async_session, + ) + + assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR + assert ( + exc_info.value.detail == "Failed to delete the Player due to a database error." + ) + mock_retrieve_by_squad_number.assert_awaited_once_with( + mock_async_session, existing_player_schema.squad_number + ) + mock_delete.assert_awaited_once_with( + mock_async_session, existing_player_schema.squad_number + ) + mock_clear_cache.assert_not_awaited() diff --git a/tests/unit/test_player_service.py b/tests/unit/test_player_service.py new file mode 100644 index 00000000..0dcc67dd --- /dev/null +++ b/tests/unit/test_player_service.py @@ -0,0 +1,371 @@ +""" +Test cases for the PlayerService. +""" + +from unittest.mock import AsyncMock, Mock, patch +from uuid import UUID + +import pytest +from sqlalchemy.exc import SQLAlchemyError +from sqlalchemy.ext.asyncio import AsyncSession + +from models.player_model import PlayerRequestModel +from schemas.player_schema import Player +from services.player_service import ( + create_async, + delete_by_squad_number_async, + retrieve_all_async, + retrieve_by_id_async, + retrieve_by_squad_number_async, + update_by_squad_number_async, +) +from tests.player_fake import existing_player, nonexistent_player, unknown_player + + +@pytest.fixture +def existing_player_request_model(): + """Fixture for an existing PlayerRequestModel.""" + return PlayerRequestModel( + first_name="Damián", + middle_name="Emiliano", + last_name="Martínez", + date_of_birth="1992-09-02T00:00:00.000Z", + squad_number=23, + position="Goalkeeper", + abbr_position="GK", + team="Aston Villa FC", + league="Premier League", + starting11=True, + ) + + +@pytest.fixture +def existing_player_schema(): + """Fixture for an existing Player schema.""" + return Player( + id=UUID("01772c59-43f0-5d85-b913-c78e4e281452"), + first_name="Damián", + middle_name="Emiliano", + last_name="Martínez", + date_of_birth="1992-09-02T00:00:00.000Z", + squad_number=23, + position="Goalkeeper", + abbr_position="GK", + team="Aston Villa FC", + league="Premier League", + starting11=True, + ) + + +@pytest.mark.anyio +async def test_create_async_success(existing_player_request_model): + """Test the successful creation of a Player.""" + mock_session = AsyncMock(spec=AsyncSession) + + result = await create_async(mock_session, existing_player_request_model) + + assert result is not None + mock_session.add.assert_called_once_with(result) + mock_session.commit.assert_awaited_once() + mock_session.refresh.assert_awaited_once_with(result) + + +@pytest.mark.anyio +async def test_create_async_database_error(existing_player_request_model): + """Return None and roll back when player creation raises a database error.""" + mock_session = AsyncMock(spec=AsyncSession) + mock_session.commit.side_effect = SQLAlchemyError("Connection timeout") + + result = await create_async(mock_session, existing_player_request_model) + + assert result is None + mock_session.commit.assert_awaited_once() + mock_session.rollback.assert_awaited_once() + mock_session.refresh.assert_not_awaited() + + +@pytest.mark.anyio +async def test_retrieve_all_async(): + """Test the retrieval of all players.""" + mock_session = AsyncMock(spec=AsyncSession) + mock_result = Mock() + mock_players = [existing_player(), nonexistent_player(), unknown_player()] + mock_result.scalars.return_value.all.return_value = mock_players + + mock_session.execute.return_value = mock_result + + result = await retrieve_all_async(mock_session) + + assert result == mock_players + mock_session.execute.assert_awaited_once() + + +@pytest.mark.anyio +async def test_retrieve_all_async_empty(): + """Test the retrieval of all players when no players exist.""" + mock_session = AsyncMock(spec=AsyncSession) + mock_result = Mock() + mock_result.scalars.return_value.all.return_value = [] + + mock_session.execute.return_value = mock_result + + result = await retrieve_all_async(mock_session) + + assert result == [] + mock_session.execute.assert_awaited_once() + + +@pytest.mark.anyio +async def test_retrieve_by_id_async(existing_player_schema): + """Test the retrieval of a player by ID.""" + mock_session = AsyncMock(spec=AsyncSession) + + mock_session.get.return_value = existing_player_schema + + result = await retrieve_by_id_async(mock_session, existing_player_schema.id) + + assert result == existing_player_schema + mock_session.get.assert_awaited_once_with(Player, existing_player_schema.id) + + +@pytest.mark.anyio +async def test_retrieve_by_id_async_not_found(): + """Test the retrieval of a player by ID when the player does not exist.""" + mock_session = AsyncMock(spec=AsyncSession) + non_existent_id = UUID("00000000-0000-0000-0000-000000000000") + + mock_session.get.return_value = None + + result = await retrieve_by_id_async(mock_session, non_existent_id) + + assert result is None + mock_session.get.assert_awaited_once_with(Player, non_existent_id) + + +@pytest.mark.anyio +async def test_retrieve_by_squad_number_async(existing_player_schema): + """Test the retrieval of a player by Squad Number.""" + mock_session = AsyncMock(spec=AsyncSession) + mock_result = Mock() + mock_result.scalars.return_value.first.return_value = existing_player_schema + + mock_session.execute.return_value = mock_result + + result = await retrieve_by_squad_number_async( + mock_session, + existing_player_schema.squad_number, + ) + + assert result == existing_player_schema + mock_session.execute.assert_awaited_once() + statement = mock_session.execute.await_args.args[0] + expected = Player.squad_number == existing_player_schema.squad_number + assert statement.whereclause.compare(expected) + + +@pytest.mark.anyio +async def test_retrieve_by_squad_number_async_not_found(): + """Test the retrieval of a player by Squad Number when the player does not exist.""" + mock_session = AsyncMock(spec=AsyncSession) + non_existent_squad_number = 99 + + mock_result = Mock() + mock_result.scalars.return_value.first.return_value = None + mock_session.execute.return_value = mock_result + + result = await retrieve_by_squad_number_async( + mock_session, non_existent_squad_number + ) + + assert result is None + + mock_session.execute.assert_awaited_once() + statement = mock_session.execute.await_args.args[0] + expected = Player.squad_number == non_existent_squad_number + assert statement.whereclause.compare(expected) + + +@pytest.mark.anyio +async def test_update_by_squad_number_async_success( + existing_player_request_model, existing_player_schema +): + """Test the successful update of a player by Squad Number.""" + mock_session = AsyncMock(spec=AsyncSession) + + existing_player_request_model.first_name = "UpdatedFirstName" + existing_player_request_model.middle_name = "UpdatedMiddleName" + existing_player_request_model.last_name = "UpdatedLastName" + existing_player_request_model.position = "UpdatedPosition" + existing_player_request_model.abbr_position = "UPD" + existing_player_request_model.team = "UpdatedTeam" + existing_player_request_model.league = "UpdatedLeague" + existing_player_request_model.starting11 = not existing_player_schema.starting11 + + with patch( + "services.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve: + mock_retrieve.return_value = existing_player_schema + + result = await update_by_squad_number_async( + mock_session, + existing_player_schema.squad_number, + existing_player_request_model, + ) + + assert result is True + mock_retrieve.assert_awaited_once_with( + mock_session, existing_player_schema.squad_number + ) + mock_session.commit.assert_awaited_once() + mock_session.rollback.assert_not_awaited() + + assert existing_player_schema.first_name == existing_player_request_model.first_name + assert ( + existing_player_schema.middle_name == existing_player_request_model.middle_name + ) + assert existing_player_schema.last_name == existing_player_request_model.last_name + assert ( + existing_player_schema.date_of_birth + == existing_player_request_model.date_of_birth + ) + assert ( + existing_player_schema.squad_number + == existing_player_request_model.squad_number + ) + assert existing_player_schema.position == existing_player_request_model.position + assert ( + existing_player_schema.abbr_position + == existing_player_request_model.abbr_position + ) + assert existing_player_schema.team == existing_player_request_model.team + assert existing_player_schema.league == existing_player_request_model.league + assert existing_player_schema.starting11 == existing_player_request_model.starting11 + + +@pytest.mark.anyio +async def test_update_by_squad_number_async_not_found( + existing_player_request_model, +): + """Test the update of a player by Squad Number when the player does not exist.""" + mock_session = AsyncMock(spec=AsyncSession) + non_existent_squad_number = 99 + + with patch( + "services.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve: + mock_retrieve.return_value = None + + result = await update_by_squad_number_async( + mock_session, + non_existent_squad_number, + existing_player_request_model, + ) + + assert result is False + mock_retrieve.assert_awaited_once_with(mock_session, non_existent_squad_number) + mock_session.commit.assert_not_awaited() + mock_session.rollback.assert_not_awaited() + + +@pytest.mark.anyio +async def test_update_by_squad_number_async_database_error( + existing_player_request_model, existing_player_schema +): + """Test the update of a player by Squad Number when a database error occurs.""" + mock_session = AsyncMock(spec=AsyncSession) + + with patch( + "services.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve: + mock_retrieve.return_value = existing_player_schema + mock_session.commit.side_effect = SQLAlchemyError("Connection timeout") + + result = await update_by_squad_number_async( + mock_session, + existing_player_schema.squad_number, + existing_player_request_model, + ) + + assert result is False + mock_retrieve.assert_awaited_once_with( + mock_session, existing_player_schema.squad_number + ) + mock_session.commit.assert_awaited_once() + mock_session.rollback.assert_awaited_once() + + +@pytest.mark.anyio +async def test_delete_by_squad_number_async_success(existing_player_schema): + """Test the successful deletion of a player by Squad Number.""" + mock_session = AsyncMock(spec=AsyncSession) + + with patch( + "services.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve: + mock_retrieve.return_value = existing_player_schema + + result = await delete_by_squad_number_async( + mock_session, + existing_player_schema.squad_number, + ) + + assert result is True + mock_retrieve.assert_awaited_once_with( + mock_session, existing_player_schema.squad_number + ) + mock_session.delete.assert_awaited_once_with(existing_player_schema) + mock_session.commit.assert_awaited_once() + mock_session.rollback.assert_not_awaited() + + +@pytest.mark.anyio +async def test_delete_by_squad_number_async_not_found(): + """Test the deletion of a player by Squad Number when the player does not exist.""" + mock_session = AsyncMock(spec=AsyncSession) + non_existent_squad_number = 99 + + with patch( + "services.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve: + mock_retrieve.return_value = None + + result = await delete_by_squad_number_async( + mock_session, non_existent_squad_number + ) + + assert result is False + mock_retrieve.assert_awaited_once_with(mock_session, non_existent_squad_number) + mock_session.delete.assert_not_awaited() + mock_session.commit.assert_not_awaited() + mock_session.rollback.assert_not_awaited() + + +@pytest.mark.anyio +async def test_delete_by_squad_number_async_database_error(existing_player_schema): + """Test the deletion of a player by Squad Number when a database error occurs.""" + mock_session = AsyncMock(spec=AsyncSession) + + with patch( + "services.player_service.retrieve_by_squad_number_async", + new_callable=AsyncMock, + ) as mock_retrieve: + mock_retrieve.return_value = existing_player_schema + mock_session.commit.side_effect = SQLAlchemyError("Connection timeout") + + result = await delete_by_squad_number_async( + mock_session, + existing_player_schema.squad_number, + ) + + assert result is False + mock_retrieve.assert_awaited_once_with( + mock_session, existing_player_schema.squad_number + ) + mock_session.delete.assert_awaited_once_with(existing_player_schema) + mock_session.commit.assert_awaited_once() + mock_session.rollback.assert_awaited_once()