DOCX Fast Create Browser Smoke

This opt-in Playwright smoke verifies the browser-facing DOCX Fast create route without changing the default gateway route table. It opens the real import surface, seeds browser auth and organization state, and asserts that the browser-observed POST /api/exam-import/docx-fast-jobs response came through the non-default native exam-import-docx-fast-create 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-create-native-localhost-example.json
• document-service and object storage when using UI upload mode
• gateway route table: GATEWAY_ROUTE_TABLE=deploy/gateway/routes.import-create-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
IMPORT_CREATE_BROWSER_SELF_TEST=1 make test-import-create-browser

Live browser mode using the real DOCX Fast upload input:

cd go-platform
IMPORT_CREATE_BROWSER_AUTHORIZATION='Bearer <teacher-token>' \
IMPORT_CREATE_BROWSER_ORGANIZATION_ID=<org-id> \
IMPORT_CREATE_BROWSER_DOCX_FILE=/Users/velikho/Desktop/test-hoctapaz/sample.docx \
make test-import-create-browser

Live browser mode using an already uploaded DOCX object:

cd go-platform
IMPORT_CREATE_BROWSER_AUTHORIZATION='Bearer <teacher-token>' \
IMPORT_CREATE_BROWSER_ORGANIZATION_ID=<org-id> \
IMPORT_CREATE_BROWSER_STORAGE_KEY=<uploaded-docx-storage-key> \
IMPORT_CREATE_BROWSER_FILE_NAME=sample.docx \
make test-import-create-browser

Question-bank bulk import surface:

IMPORT_CREATE_BROWSER_PATH=/teacher/questions/import \
IMPORT_CREATE_BROWSER_AUTO_APPROVE=1 \
IMPORT_CREATE_BROWSER_WORKFLOW=exam \
IMPORT_CREATE_BROWSER_AUTHORIZATION='Bearer <teacher-token>' \
IMPORT_CREATE_BROWSER_ORGANIZATION_ID=<org-id> \
IMPORT_CREATE_BROWSER_STORAGE_KEY=<uploaded-docx-storage-key> \
make test-import-create-browser

Teacher Native Candidate

The current Teacher surface is an opt-in browser proof, not a default route:

IMPORT_CREATE_BROWSER_PATH='/teacher/questions/import?teacherImportGateway=native' \
IMPORT_CREATE_BROWSER_DOCX_FILE=/Users/velikho/Desktop/test-hoctapaz/sample.docx \
IMPORT_CREATE_BROWSER_AUTHORIZATION='Bearer <teacher-token>' \
IMPORT_CREATE_BROWSER_ORGANIZATION_ID=<org-id> \
IMPORT_CREATE_BROWSER_ROUTE_TABLE=deploy/gateway/routes.teacher-docx-fast-native-localhost-example.json \
IMPORT_CREATE_BROWSER_MAX_LATENCY_MS=60000 \
WEB_BASE_URL=http://127.0.0.1:<teacher-vite-port> \
GATEWAY_BASE_URL=http://127.0.0.1:<gateway-port> \
make test-import-create-browser

It seeds the browser's expiring hoctapaz.goPlatform.gatewaySession, selects the real #teacher-import-file, and follows the UI button through the native editor link. The runner records only a hash of the opaque sourceAssetId.

The Teacher route table must contain the exact owner-scoped source-upload and DOCX Fast create routes plus the one-segment job-detail read route. Broad /api/exam-import and fallback routes remain legacy_proxy.

Useful optional variables:

• IMPORT_CREATE_BROWSER_HEADLESS=0 to see Chromium.
• IMPORT_CREATE_BROWSER_PATH=/teacher/exams/create?tab=import&mode=docx-fast to override the page path.
• IMPORT_CREATE_BROWSER_WORKFLOW=tron-de to use the alternate workflow query.
• IMPORT_CREATE_BROWSER_ARTIFACT_DIR=output/playwright/<name> to control artifact output.

Assertions

The smoke fails unless:

• the route table has exact POST /api/exam-import/docx-fast-jobs as native_write
• the route targets /v1/import/docx/docx-fast-jobs
• the route requires auth, organization, and ADMIN/TEACHER
• broad /api/exam-import and fallback stay legacy_proxy
• the browser observes X-Hoctapaz-Gateway-Route: exam-import-docx-fast-create
• the browser observes X-Hoctapaz-Gateway-Route-State: native_write
• the create response is the legacy success envelope with source: docx-fast and message DOCX Fast import job queued
• in Teacher native mode, source upload, job creation, and polling all use the configured Gateway origin and expose the expected native route/state headers
• in Teacher native mode, the create body reuses the exact source-upload asset, the job reaches COMPLETED, and the native editor link is opened within IMPORT_CREATE_BROWSER_MAX_LATENCY_MS
• Teacher artifacts contain redacted sequence metadata, browser Resource Timing, latency, and an editor screenshot; they do not contain raw auth or source IDs

Live artifacts are written under output/playwright/ and include request body when applicable, response headers, response body, a summary file, and a 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 does not change route tables or frontend source.