Skip to content

test: pin the Python location client's failure paths - #269

Merged
dmccoystephenson merged 1 commit into
mainfrom
feature/location-client-failure-paths
Nov 13, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
feature/location-client-failure-paths

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

A Stage B (unit-test expansion) cycle covering the Python client's LocationService (src/main/python/preponderous/viron/services/locationService.py). It follows the entity (#266), grid (#267) and environment (#268) clients and completes the set. Thirty-six characterization tests are added to src/test/python/preponderous/viron/services/test_locationService.py. No production code is changed.

What is now pinned:

  • A 404 becomes a plain Exception, not an HTTPError. Unlike GridService and EnvironmentService, the location client checks a 404 itself before raise_for_status. This applies to get_location_by_id, get_neighbors, get_location_of_entity, get_entity_ids_at_location, is_location_occupied, add_entity_to_location, remove_entity_from_current_location and move_entity_to_location. The exception's exact message is pinned, and raise_for_status and json() are confirmed not to be called. get_location_of_entity's 404 had no test before this PR.
  • A 409 on either placement write becomes a plain Exception. For add_entity_to_location the message is "Entity N is already placed at another location", and for move_entity_to_location it is "Target location N is already occupied".
  • The client maps no other status. The move's 400s (the target is in another grid or is not adjacent) and the lock-wait 503 on both placement writes reach the caller as HTTPError. A 400 on any of the five list reads does too, and the list reads never read the body in that case.
  • get_placements(0) sends environmentId=0. The method compares against None, so a zero is not dropped (the server's @Min(1) then rejects it).
  • Transport errors propagate unwrapped (ConnectionError) on reads and on all three write verbs.
  • The bearer token reaches every write: add, remove, remove-from-current and move. Before this PR only get_all_locations was checked.
  • A null body is not guarded. The eight model-building reads raise TypeError. get_entity_ids_at_location and is_location_occupied return the decoded body unchanged, so is_location_occupied can return None rather than a bool.

The split between plain Exception and HTTPError is recorded as current behaviour, not endorsed as correct. If the clients are later made consistent, these tests mark exactly what would change.

Deferred issues

Test plan

  • pytest -q (pytest 9.0.3): 201 passed (165 before, 36 new)
  • python3 -m pytest -q (pytest 7.1.3, Python 3.8): 201 passed
  • CI green on the PR head. The CI workflow's Python jobs run this suite. No Java file is touched.

No tracking issue — gap found during triage.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric (one intrinsic pass, anchored on CI run 43375094535 and a local mutation check):

  • Scope: PASS — one file changed, src/test/python/preponderous/viron/services/test_locationService.py (+196/−1). The only pre-existing line touched is the added import requests.
  • Tests-new: PASS (not applicable) — no production function is added or changed.
  • Tests-fix: not applicable — no bug fix. As a bite check instead, removing the client's 404 branch in get_location_of_entity made test_lookup_not_found_raises_plain_exception_without_reading_body[of_entity] fail (1 failed, 64 passed). The mutation was reverted with git checkout.
  • Sibling structure: PASS — the new section mirrors test: pin the Python entity client's failure paths #266–test: pin the Python environment client's failure paths #268: a header comment on failure paths, _error_response, AUTH_HEADERS / _authed_service, and a closing test_empty_body_raises_type_error.
  • Sibling renames: not applicable — nothing is renamed.
  • Docs: PASS — the change is test-only. No row of the documentation table (OpenAPI, MVP, PLANNING, REBUILD_PLAN, tickets, README, Postman) describes client test coverage.
  • Issue resolution: not applicable — no Closes. The gap was found during triage.
  • CI: PASS — build, python-client (3.8) and python-client (3.12) are green on the PR head.
  • DTO boundary / Spec alignment / Override correctness: not applicable — no Java is touched. The 400 and 503 statuses that the move and add tests assume were checked against docs/openapi/viron-api.json, where both PUT routes list 400, 404, 409 and 503.
  • Java/Python parallelism: not applicable — no behaviour changed on either side.

Observations (judgment calls, not blocking):

  • test_locationService.py, test_write_sends_bearer_token — the mocked status is 204 for every write. The spec answers the add route with 200, but the client never reads the status on a successful write, so the value does not affect the assertion.
  • The plain-Exception vs HTTPError split is pinned as current behaviour, not endorsed. Making the four clients consistent would be a contract change to the Python client, and it is left for a separate decision rather than being fixed under a test-expansion cycle.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 6734a26 into main Nov 13, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the feature/location-client-failure-paths branch November 13, 2026 05:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant