DOCX Import Library Browser Smoke

This opt-in Playwright smoke verifies the browser-facing DOCX import library route without changing the default gateway route table. It opens the real /teacher/exams/library page, seeds browser auth and organization state, and asserts that the browser-observed GET /api/exam-import/teacher-library response came through the non-default native exam-import-teacher-library gateway route.

Required Runtime

Start these processes before live mode:

• Next.js web app, default WEB_BASE_URL=http://localhost:3000
• API gateway, default GATEWAY_BASE_URL=http://localhost:8085
• docx-import-service, default target from deploy/gateway/routes.import-status-native-localhost-example.json
• gateway route table: GATEWAY_ROUTE_TABLE=deploy/gateway/routes.import-status-native-localhost-example.json

The web app must be started with NEXT_PUBLIC_API_URL pointing at the gateway base URL. If the frontend points directly at the legacy API process, the smoke fails because the response will not include gateway route headers.

Run

Static self-test:

cd go-platform
DOCX_IMPORT_LIBRARY_BROWSER_SELF_TEST=1 make test-docx-import-library-browser

Live browser mode:

cd go-platform
DOCX_IMPORT_LIBRARY_BROWSER_AUTHORIZATION='Bearer <teacher-token>' \
DOCX_IMPORT_LIBRARY_BROWSER_ORGANIZATION_ID=<org-id> \
make test-docx-import-library-browser

Live mode with a specific pending/processing job and BullMQ queue assertion:

cd go-platform
DOCX_IMPORT_LIBRARY_BROWSER_AUTHORIZATION='Bearer <teacher-token>' \
DOCX_IMPORT_LIBRARY_BROWSER_ORGANIZATION_ID=<org-id> \
DOCX_IMPORT_LIBRARY_BROWSER_JOB_ID=<job-id> \
DOCX_IMPORT_LIBRARY_BROWSER_EXPECT_QUEUE_STATUS=waiting \
DOCX_IMPORT_LIBRARY_BROWSER_EXPECT_MIN_TOTAL_PENDING=1 \
make test-docx-import-library-browser

Useful optional variables:

• DOCX_IMPORT_LIBRARY_BROWSER_HEADLESS=0 to see Chromium.
• DOCX_IMPORT_LIBRARY_BROWSER_PATH=/teacher/exams/library to override the page path.
• DOCX_IMPORT_LIBRARY_BROWSER_REQUIRE_ITEMS=1 to fail on an empty list.
• DOCX_IMPORT_LIBRARY_BROWSER_REQUIRE_QUEUE=0 to search for a job without asserting its queue snapshot.
• DOCX_IMPORT_LIBRARY_BROWSER_ARTIFACT_DIR=output/playwright/<name> to control artifact output.

Assertions

The smoke fails unless:

• the route table has exam-import-teacher-library as exact GETnative_read
• the route table has exam-import-job-status and imports-job-status as native read status carve-outs
• broad /api/exam-import and /api/imports remain legacy_proxy
• the browser observes X-Hoctapaz-Gateway-Route: exam-import-teacher-library
• the browser observes X-Hoctapaz-Gateway-Route-State: native_read
• the list response contains a legacy-compatible rows/meta shape
• when DOCX_IMPORT_LIBRARY_BROWSER_JOB_ID is set, the searched response contains that job id
• when queue assertion is enabled, the job row contains the legacy-shaped BullMQ queue fields

Live artifacts are written under output/playwright/ and include response headers, response body, a summary file, and a full-page screenshot.

Rollback

Switch GATEWAY_ROUTE_TABLE back to deploy/gateway/routes.json, remove the native route-table entries, or set them to legacy_proxy. This smoke is read-only and does not modify import jobs.