From 7191400b5bdcb4559a7c91c7ba3bfffac38edb80 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Wed, 25 Mar 2026 11:19:40 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20update=20refractor=20test=20plan=20?= =?UTF-8?q?=E2=80=94=20resolve=20list=20endpoint=20gap,=20add=20API=20test?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Mark CRITICAL missing endpoint gap as resolved (database PR #173 merged) - Add REF-API-06 through REF-API-10 covering the new GET /refractor/cards list endpoint (team filter, card_type, tier, progress, pagination) - Update prerequisites, execution checklist, and time estimates - Total test cases: 87 (was 82) Co-Authored-By: Claude Opus 4.6 (1M context) --- tests/refractor-integration-test-plan.md | 77 +++++++++++++++--------- 1 file changed, 50 insertions(+), 27 deletions(-) diff --git a/tests/refractor-integration-test-plan.md b/tests/refractor-integration-test-plan.md index e4c1919..7cd9c48 100644 --- a/tests/refractor-integration-test-plan.md +++ b/tests/refractor-integration-test-plan.md @@ -52,6 +52,7 @@ Before running these tests, ensure the following state exists: - [ ] Refractor tracks are seeded: `GET /api/v2/refractor/tracks` returns at least 3 tracks (batter, sp, rp) - [ ] At least one RefractorCardState row exists for a card on the test team - [ ] Verify manually: `GET /api/v2/refractor/cards/{CARD_BATTER}` returns a valid response +- [ ] Verify list endpoint: `GET /api/v2/refractor/cards?team_id={TEAM_ID}` returns cards for the test team ### Data Setup Script (run against dev API) If refractor state does not yet exist for test cards, trigger initialization: @@ -103,6 +104,44 @@ API layer is functional. Execute via shell or Playwright network interception. | **Expected** | HTTP 404 | | **Pass criteria** | Status code is 404 (confirms evolution->refractor rename is complete) | +### REF-API-06: Team-level card list endpoint +| Field | Value | +|---|---| +| **Command** | `curl -s "https://pddev.manticorum.com/api/v2/refractor/cards?team_id=${TEAM_ID}" -H "Authorization: Bearer $TOKEN"` | +| **Expected** | JSON with `count` >= 1 and `items` array containing card state objects | +| **Pass criteria** | 1. `count` reflects total cards with refractor state for the team | +| | 2. Each item has `player_id`, `team_id`, `current_tier`, `current_value`, `progress_pct`, `player_name` | +| | 3. Items sorted by `current_tier` DESC, `current_value` DESC | + +### REF-API-07: Card list with card_type filter +| Field | Value | +|---|---| +| **Command** | `curl -s "https://pddev.manticorum.com/api/v2/refractor/cards?team_id=${TEAM_ID}&card_type=batter" -H "Authorization: Bearer $TOKEN"` | +| **Expected** | JSON with only batter card states | +| **Pass criteria** | All items have batter track; count <= total from REF-API-06 | + +### REF-API-08: Card list with tier filter +| Field | Value | +|---|---| +| **Command** | `curl -s "https://pddev.manticorum.com/api/v2/refractor/cards?team_id=${TEAM_ID}&tier=0" -H "Authorization: Bearer $TOKEN"` | +| **Expected** | JSON with only T0 card states | +| **Pass criteria** | All items have `current_tier: 0` | + +### REF-API-09: Card list with progress=close filter +| Field | Value | +|---|---| +| **Command** | `curl -s "https://pddev.manticorum.com/api/v2/refractor/cards?team_id=${TEAM_ID}&progress=close" -H "Authorization: Bearer $TOKEN"` | +| **Expected** | JSON with only cards at >= 80% of next tier threshold | +| **Pass criteria** | Each item's `progress_pct` >= 80.0; no fully evolved cards | + +### REF-API-10: Card list pagination +| Field | Value | +|---|---| +| **Command** | `curl -s "https://pddev.manticorum.com/api/v2/refractor/cards?team_id=${TEAM_ID}&limit=2&offset=0" -H "Authorization: Bearer $TOKEN"` | +| **Expected** | JSON with `count` reflecting total (not page size) and `items` array with at most 2 entries | +| **Pass criteria** | 1. `count` same as REF-API-06 (total matching, not page size) | +| | 2. `items` length <= 2 | + --- ## 2. /refractor status -- Basic Functionality @@ -584,32 +623,16 @@ commands that display card information. ## Known Gaps and Risks -### CRITICAL: Missing team-level refractor cards list endpoint +### ~~RESOLVED: Team-level refractor cards list endpoint~~ -The `/refractor status` slash command calls `db_get("refractor/cards", params=[("team_id", team_id)])`, -which sends `GET /api/v2/refractor/cards?team_id=X` to the API. +The `GET /api/v2/refractor/cards` list endpoint was added in database PR #173 +(merged 2026-03-25). It accepts `team_id` (required), `card_type`, `tier`, +`season`, `progress`, `limit`, and `offset` query parameters. The response +includes `progress_pct` (computed) and `player_name` (via LEFT JOIN on Player). +Sorting: `current_tier` DESC, `current_value` DESC. A non-unique index on +`refractor_card_state.team_id` was added for query performance. -However, the API only defines these refractor routes: -- `GET /refractor/tracks` -- list all tracks -- `GET /refractor/tracks/{track_id}` -- single track -- `GET /refractor/cards/{card_id}` -- single card state by card ID -- `POST /refractor/cards/{card_id}/evaluate` -- force evaluate one card -- `POST /refractor/evaluate-game/{game_id}` -- evaluate all players in a game - -There is **no** `GET /refractor/cards` (list) endpoint that accepts a `team_id` -query parameter. This means `/refractor status` will likely receive a 404 or -routing error from the API, causing the "No refractor data found for your team" -fallback message for ALL users. - -**Action required**: Either: -1. Add a `GET /refractor/cards` list endpoint to the database API that accepts - `team_id`, `card_type`, `season`, and `tier` query parameters, OR -2. Restructure the bot command to fetch the team's card list first, then call - `GET /refractor/cards/{card_id}` for each card individually (N+1 problem). - -This gap should be verified immediately by running REF-01 against the dev server. -If the command returns "No refractor data found for your team" even when -refractor state exists, this is the cause. +Test cases REF-API-06 through REF-API-10 now cover this endpoint directly. ### In-game card display does not show badges @@ -642,7 +665,7 @@ design but means tier-up notifications are best-effort. Run order for Playwright automation: -1. [ ] Execute REF-API-01 through REF-API-05 (API health) +1. [ ] Execute REF-API-01 through REF-API-10 (API health + list endpoint) 2. [ ] Execute REF-01 through REF-06 (basic /refractor status) 3. [ ] Execute REF-10 through REF-19 (filters) 4. [ ] Execute REF-20 through REF-23 (pagination) @@ -654,7 +677,7 @@ Run order for Playwright automation: 10. [ ] Execute REF-80 through REF-82 (force-evaluate API) ### Approximate Time Estimates -- API health checks: 1-2 minutes +- API health checks + list endpoint (REF-API-01 through REF-API-10): 2-3 minutes - /refractor status tests (REF-01 through REF-34): 10-15 minutes - Tier badge tests (REF-40 through REF-45): 5-10 minutes - Game simulation tests (REF-50 through REF-55): 15-30 minutes (depends on game length) @@ -662,4 +685,4 @@ Run order for Playwright automation: - Cross-command tests (REF-70 through REF-72): 5 minutes - Force-evaluate API tests (REF-80 through REF-82): 2-3 minutes -**Total estimated time**: 50-85 minutes for full suite +**Total estimated time**: 50-90 minutes for full suite (87 test cases)