docs: consolidate design documentation and standardize crate English
This commit is contained in:
@@ -1,52 +1,9 @@
|
||||
# T-724 browser fixture validation
|
||||
# Drive Browser fixture
|
||||
|
||||
These tests serve the real static production Web shell against a loopback, in-memory API fixture. They are **not actual Backend/DB/LocalFileSystem authorization or round-trip evidence**. The parent owns the separate real API checks.
|
||||
production static shellをloopbackのin-memory API fixtureに接続し、描画、操作、遅延応答、draft保持を検証する。Backend／DB／blob storageの認可を証明するテストではない。
|
||||
|
||||
## Runtime prerequisites
|
||||
- `fixture-api.test.ts`: fixtureとWeb parserの契約一致。
|
||||
- `drive.browser.test.ts`: production画面の操作と要求の整合。
|
||||
- `responsive.browser.test.ts` / `capture-visual.ts`: responsive検査と画像・診断の保存。
|
||||
|
||||
Deno and Playwright Chromium must be available. The server binds loopback only and owns/cleans up its shared Home fixture subprocess. Tests use an ephemeral port and independent fixture state; no real workspace data, credentials, git operations, environment test switches, or UI/CSS fixture branches are used.
|
||||
|
||||
The parent must confirm UI readiness before the production build and browser run. Tests intentionally never build automatically.
|
||||
|
||||
```sh
|
||||
# Narrow API-fixture compatibility checks (safe before UI readiness)
|
||||
deno test --config web/workspace/test/drive-browser/deno.json --allow-read web/workspace/test/drive-browser/fixture-api.test.ts
|
||||
|
||||
# After explicit parent UI-ready signal and successful production build only:
|
||||
deno test --config web/workspace/test/drive-browser/deno.json --allow-env --allow-net --allow-read --allow-write --allow-run --allow-sys web/workspace/test/drive-browser/drive.browser.test.ts
|
||||
|
||||
# Responsive audit, with optional frozen production site and artifact suffix:
|
||||
deno test --config web/workspace/test/drive-browser/deno.json --allow-env --allow-net --allow-read --allow-write --allow-run --allow-sys web/workspace/test/drive-browser/responsive.browser.test.ts -- web/workspace/.svelte-kit/t724/verified-build/site final-reviewed
|
||||
|
||||
# Official tools/web-ux bundles; no build is performed by this runner.
|
||||
deno run --config web/workspace/test/drive-browser/deno.json --allow-env --allow-net --allow-read --allow-write --allow-run --allow-sys web/workspace/test/drive-browser/capture-visual.ts before <unique-run-suffix>
|
||||
deno run --config web/workspace/test/drive-browser/deno.json --allow-env --allow-net --allow-read --allow-write --allow-run --allow-sys web/workspace/test/drive-browser/capture-visual.ts after <unique-run-suffix> [workdir-relative-production-site]
|
||||
```
|
||||
|
||||
## Fixture API
|
||||
|
||||
Start `tools/web-ux/drive-fixture/server.ts <port> <build-root>` with `--allow-net --allow-read --allow-run --allow-env`. It extends the shared Home/settings API fixture through a loopback proxy and implements Drive root/list/metadata/search/read-text/read-chunk/download/mutate/upload/request-status/grants APIs. Response wire types derive from generated Drive DTOs; current client parsers are exercised by the fixture compatibility tests.
|
||||
|
||||
- Root ID `9007199254740993` tests lossless decimal references.
|
||||
- `2`: folder 資料; `3`: Markdown README; `4`: text inside folder 2.
|
||||
- `5`: valid synthetic 1200×800 `landscape.png` (16,813 compressed bytes), generated as real binary PNG data by `tools/web-ux/drive-fixture/raster.ts`; `6`: empty text; `7`: undecodable PNG; `8`: SVG download-only; `9`: text exceeding 64 KiB; `10`: long Japanese name; `11`: valid 64 KiB NUL text whose escaped JSON exceeds 256 KiB but stays below the separate 512 KiB JSON bound.
|
||||
- `home-member` and `*readonly*`: reads succeed, mutations are typed HTTP 403. No metadata permission flag is invented. The UI reacts to a denied operation, not speculative permission inference.
|
||||
- `*denied*`: typed HTTP 403 root/read; `*offline*`/`home-error`: typed HTTP 503; `*empty*`: empty successful root list; `*paged*`: 240 additional nodes.
|
||||
- `POST /__fixture/fault` JSON `{workspace, mode}`: one-shot `conflict` or committed `unknown` mutation response; persistent `image_error` binary fetch failure.
|
||||
- `home-owner`/`home-member`/`home-long`: representative authoritative Worker catalogs; REST and subscription projections come from the same generated-shape records. `home-long` includes long display names and opaque Runtime/Worker IDs. `workers-error` intentionally fails catalog reads with HTTP 503.
|
||||
- `GET /__fixture/log`: observable API request IDs/methods/paths/node IDs/CAS observed committed requests for identity and no-resend assertions.
|
||||
- `POST /__fixture/reset`: fresh in-memory state.
|
||||
|
||||
Request delay/loss tests intercept the API boundary with Playwright and synchronize on gates, not guessed sleeps. They let the fixture commit before dropping/holding the response, then verify receipt query without blind upload retry.
|
||||
|
||||
## Visual evidence
|
||||
|
||||
Preserved production baseline: `.svelte-kit/t724/before-build/{site,output,build.log}`. Official bundles live below `.svelte-kit/t724/visual/`. Each contains screenshots, console/request/page diagnostics, accessibility snapshots, screenshot hashes, source commit/dirty context, and `review-context.json`.
|
||||
|
||||
Home/sidebar and Workers are captured under identical owner/member/error/empty/long conditions, light/dark at 1440/768/390/320. After captures add Drive owner/member/empty/error/denied/paged/Markdown/image/image-error/truncated surfaces, pinned rename/replace observed committed request forms, and owner grant selection/read-only/read-write/revoked states. Expected injected 503/403 diagnostics and superseded breadcrumb metadata aborts remain in official context; `diagnostic-disposition.json` explicitly separates unexpected diagnostics. CLI `completed-with-errors` is not relabeled a visual pass.
|
||||
|
||||
The production shell scrolls `main` internally, so `fullPage` does not expand that scroll panel. Capture points use ordinary keyboard focus to show the actual form or the top denial state; no CSS/DOM screenshot override is applied. The responsive audit separately records document/main/table-region geometry, visible keyboard focus, and page errors across the full theme/viewport matrix. Raster checks wait for actual decoding, assert natural dimensions 1200×800, preserve the 3:2 aspect ratio, and constrain the rendered box by both the available width and 60vh height at all four widths/both themes.
|
||||
|
||||
The Drive browser suite also exercises the file-browser redesign at 1440/768/390/320px in light/dark themes: menu placement, native-dialog focus and Escape restoration, folder creation, search, and destination-folder navigation. Screenshots are written to `.svelte-kit/drive-redesign/` for the list, New menu, creation dialog, Markdown preview, and move dialog. Component tests cover failed/paged destination reads, exclusion of files and the moving folder itself, and pinned mutation observed committed requests. These checks use the same fixture boundary, not a live Backend.
|
||||
|
||||
Parent and reviewer must open images and inspect context before asserting visual acceptance. In particular, a successful capture command is not sufficient and HTTP 200 does not excuse visible UI errors.
|
||||
fixtureは実Workspaceや資格情報を使わず、所有subprocessを片付ける。テストは自動buildを行わない。検証対象のstatic生成物を明示し、画像と診断を確認してから視覚面の合否を判断する。実HTTP／storageの保証は [別harness](../drive-real-api/README.md) で検証する。
|
||||
|
||||
@@ -1,47 +1,7 @@
|
||||
# Real Drive API/Web roundtrip (not the browser fixture)
|
||||
# Drive実API roundtrip
|
||||
|
||||
This harness uses a fresh RAII temporary directory, real Server SQLite records, FeatureStorage Drive nodes and `object_store::local::LocalFileSystem` blobs. It creates a Workspace through T-717's actual repositoryless `/api/workspaces` endpoint. No repositories, user's data, live Server, environment-variable test configuration, Tools or WIP are involved.
|
||||
Rustの `drive_web_roundtrip_tests` が起動する隔離loopback Serverへ、`roundtrip.ts` がproduction Web adapterで接続する。実SQLite、FeatureStorage、LocalFileSystemを使い、認可、保存、receipt、競合、grant取消しを検証する。
|
||||
|
||||
The ordinary Rust test exercises loopback HTTP signed Worker ingress: explicit read-only/read-write grants, rejection of read-only writes, Worker-created bytes visible through Web/user API, and immediate grant revocation (even when the request also carries an owner's bearer token). Only the Runtime worker-spawn boundary uses the existing deterministic workdirless fixture runtime.
|
||||
認証情報とWorkspace identityは親harnessからstdinで受け取り、argvやログには出さない。実ユーザーデータと稼働中Serverは使わない。Denoプロセスは接続先を指定loopback originへ限定する。
|
||||
|
||||
The explicit process test starts a loopback Axum Server and launches Deno against it. `roundtrip.ts` imports the production `src/lib/workspace/drive/api.ts` adapter, not a copy or mock. Its typed `fetchFn` resolves relative paths only to the bound loopback origin and adds fixture bearer authorization. Tokens travel over stdin, not command-line arguments or logs; Rust failure diagnostics defensively redact both fixture bearer tokens. Deno has network permission only for the exact loopback port, uses no npm dependencies, and runs with `--cached-only`. Each listener is abort-on-drop, child processes are kill-on-drop, and the child has a 60-second upper timeout, without sleeps or readiness polling.
|
||||
|
||||
Coverage: Worker file list/read, Japanese folder/Markdown names, create/read/edit/download, empty files, actual PNG upload/authenticated image/download and binary update, publication receipt lookup, paged list, two authenticated accounts racing a common observed committed request (one commit/one typed conflict, no hidden retry), stable latest URL through rename and move, deleted URL and same-name recreation, and unauthorized latest URLs. The exact Workers-page `drive-grants/api.ts` adapter also lists persisted grants, creates both access levels, revokes them and re-reads durable state, and rejects member administration. Its global browser fetch is temporarily origin/auth-bound in this isolated child; network responses are never mocked. This tests real authenticated HTTP with test bearer credentials, not a Passkey/cookie browser login or a full Runtime process. UI dirty-draft retention, delayed response handling, visual review and browser cancellation belong to the **separate browser fixture**, not this API test.
|
||||
|
||||
## Registration
|
||||
|
||||
The inline `mod tests` block in `crates/workspace-server/src/server.rs` registers the module alongside the existing Drive API tests:
|
||||
|
||||
```rust
|
||||
mod drive_web_roundtrip_tests;
|
||||
```
|
||||
|
||||
No product routing modification is needed. The scoped production router is cached by the harness without starting unrelated Orchestrator hook tasks; production server ingress, authorization and API/storage handlers still run.
|
||||
|
||||
## Run
|
||||
|
||||
From the repository root:
|
||||
|
||||
```sh
|
||||
cargo test -p yoi-workspace-server --lib drive_web_roundtrip_tests
|
||||
cargo test -p yoi-workspace-server --lib drive_web_roundtrip_tests -- --ignored
|
||||
```
|
||||
|
||||
The second command requires Deno on PATH. Its ignored marker is an explicit process/E2E prerequisite, not an environment-variable gate or silent fallback. An absent Deno fails the explicit test. The ordinary real HTTP test does not require Deno.
|
||||
|
||||
The script is harness-only: it receives fresh credentials and Workspace identity from the parent over stdin; do not invoke it against a live Server. Type-check it without starting the Server:
|
||||
|
||||
```sh
|
||||
deno check --config web/workspace/test/drive-real-api/deno.json \
|
||||
web/workspace/test/drive-real-api/roundtrip.ts
|
||||
```
|
||||
|
||||
## Validation evidence
|
||||
|
||||
Validated against the production Server endpoints and Web adapter, not the browser mock routes:
|
||||
|
||||
- `cargo test -p yoi-workspace-server --lib drive_web_roundtrip_tests -- --test-threads=4`: **1 passed, 1 explicitly ignored** (the process prerequisite).
|
||||
- `cargo test -p yoi-workspace-server --lib drive_web_roundtrip_tests -- --ignored --test-threads=4`: **1 passed**; the actual Deno adapter process completed against real SQLite/LocalFileSystem HTTP.
|
||||
- `cargo test -p yoi-workspace-server -- --test-threads=4`: **693 library tests passed, 1 ignored; 11 binary tests passed; doc-tests passed**.
|
||||
|
||||
The repositoryless fixture was adjusted to retain the production runtime trust gate's exact normalized binding snapshot and to scope the reusable Runtime observation to the newly bootstrapped Workspace. Neither fix changes the API, Drive authorization policy, Tools, WIP, or browser fixtures.
|
||||
Runtime spawn境界はfixtureであり、Passkey／cookie loginや画面操作のE2Eではない。画面のdraft保持、キャンセル、視覚面は [Browser fixture](../drive-browser/README.md) が担当する。親Rust harnessとproduction adapterの両方を維持し、通信応答をmockへ置き換えない。
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
// Invoked only by the Rust loopback harness. No mocked responses, live server,
|
||||
// browser fixtures, environment variables, or bearer credentials in argv/logs.
|
||||
// Rust loopback harness専用。production adapterを実HTTPで検証し、応答をmockしない。
|
||||
// fixture認証情報はstdinから受け取り、argvやログへ出さない。画面操作の検証とは分離する。
|
||||
import {
|
||||
createDriveClient,
|
||||
type DriveClient,
|
||||
|
||||
@@ -1,93 +1,8 @@
|
||||
# Optional initial repository validation (T-717 Web portion)
|
||||
# Repository任意作成の視覚検証
|
||||
|
||||
These scenarios use the production static Workspace build and the existing
|
||||
`tools/web-ux` capture/process harness. The loopback proxy only extends the shared
|
||||
Home fixture's API responses for empty Worker lists and launch options; it does
|
||||
not replace the application shell, styles, or components. No real Workspace,
|
||||
account, repository, Runtime, or Worker is created.
|
||||
production static Workspace画面と共有 `tools/web-ux` harnessを使い、RepositoryなしのWorkspace作成、catalog、Worker起動を検証する。loopback proxyはAPI fixtureだけを拡張し、shell、style、componentはproduction実装を使う。
|
||||
|
||||
## Run
|
||||
- `optional-repository.json`: 空Workspaceとcatalogの表示条件。
|
||||
- `optional-repository-interactions.json`: 作成操作と意図した拒否応答。
|
||||
|
||||
From `web/workspace`, with the repository's pinned Chromium available:
|
||||
|
||||
```sh
|
||||
deno task build
|
||||
deno task test:browser:empty-workspace
|
||||
```
|
||||
|
||||
The browser test covers light/dark at 1440, 768, 390, and 320px: optional Git
|
||||
native validation, opting out after entering repository values, null creation
|
||||
response/navigation, zero-repository catalog reopening, normal embedded Worker
|
||||
submission without Workdir or Ticket assignment, and remote Runtime Workdir
|
||||
requirements. It uses dynamically allocated loopback ports and the existing
|
||||
owned-process cleanup harness. Screenshots and logs are ignored artifacts under
|
||||
`.svelte-kit/t717/browser`.
|
||||
|
||||
From `tools/web-ux`:
|
||||
|
||||
```sh
|
||||
deno task web-ux capture \
|
||||
--scenario ../../web/workspace/test/visual-review/optional-repository.json \
|
||||
--output ../../web/workspace/.svelte-kit/t717/visual --run-id empty-workspace
|
||||
|
||||
deno task web-ux capture \
|
||||
--scenario ../../web/workspace/test/visual-review/optional-repository-interactions.json \
|
||||
--output ../../web/workspace/.svelte-kit/t717/visual --run-id creation-interactions
|
||||
```
|
||||
|
||||
The interaction scenario intentionally rejects creation with HTTP400. Capture
|
||||
exit status 2 and the recorded request/console/visible validation errors are
|
||||
expected for `validation-error`, not evidence of a successful creation. No other
|
||||
capture error is expected. To repeat dark captures, use a scenario copy with
|
||||
`colorScheme: "dark"`, preserving the process cwd paths.
|
||||
|
||||
## Implementer-owned visual review
|
||||
|
||||
- Baseline commit: `e939cd4e4b1f6b63b81411fd7766062f2d69ad0d`.
|
||||
- Before: `.svelte-kit/t717/visual/before-final-light` and `before-dark`.
|
||||
These use an isolated build under `.svelte-kit/t717/baseline-source`, with the
|
||||
changed production form, catalog API, model, and CSS restored from baseline
|
||||
Git source. The original pre-edit light capture is also retained as
|
||||
`.svelte-kit/t717/visual/before-valid`.
|
||||
- After: `.svelte-kit/t717/visual/final-light`, `final-dark`,
|
||||
`final-interactions-light`, and `final-interactions-dark`.
|
||||
- Comparisons: `.svelte-kit/t717/visual/final-comparison-light` and
|
||||
`final-comparison-dark`.
|
||||
- Personas: synthetic owner and non-owner permission projections; catalog
|
||||
creation/reopening uses the same synthetic account.
|
||||
- Viewports: 1440, 768, 390px; additional browser screenshots/checks at 320px.
|
||||
- Themes: light and dark.
|
||||
- States: zero repositories, empty Home/Sidebar, representative member work
|
||||
records, long catalog names, unchecked/checked optional repository form,
|
||||
populated inputs, and intentional Backend validation failure.
|
||||
- Reviewed by the implementer using `ViewImage`: before/after contact sheets,
|
||||
individual narrow/mobile populated-form screenshots, and the final mobile
|
||||
dark validation-error screenshot. Reviewed context bundles and accessibility
|
||||
snapshots for document status, control names/state, screenshot hashes,
|
||||
console/page/request errors, and capture points.
|
||||
- Fixed: catalog/form clipping at narrow content widths; repository field
|
||||
disclosure/required-state handling. Chromium tests also found and fixed the
|
||||
existing repository-key HTML pattern's invalid modern-regexp character class.
|
||||
- Result: pass. All baseline and final main captures have document status 200
|
||||
and no retained browser/UI errors. Only the intentional HTTP400 interaction
|
||||
errors remain. Home, member Sidebar, and Worker launch comparisons show zero
|
||||
changed pixels; catalog changes are confined to the intended surface.
|
||||
|
||||
## Validation and limitations
|
||||
|
||||
- `deno task check`: 0 errors, 0 warnings.
|
||||
- Targeted model/catalog Deno tests: 18 passed.
|
||||
- `deno task test:component`: 29 files, 268 tests passed.
|
||||
- `deno task test:browser:empty-workspace`: passed (8 theme/width combinations).
|
||||
- `deno task build`: passed.
|
||||
- Web-scoped `git diff --check HEAD -- .`: passed.
|
||||
- `deno task test`: 522 passed, 1 pre-existing failure in
|
||||
`src/lib/workspace/console/worker-console.ui.test.ts`,
|
||||
“workspace Tickets surface provides Kanban and lifecycle controls”. It fails
|
||||
the unchanged Ticket detail source assertion at line 429. The same failure
|
||||
was reproduced against the isolated baseline source. Evidence:
|
||||
`.svelte-kit/t717/unit.log` and `baseline-ticket-failure.log`.
|
||||
- Canonical OpenAPI and generated TypeScript were regenerated together.
|
||||
The Web parser uses the generated nullable creation-response type directly.
|
||||
Backend persistence/idempotency is covered separately by Store/catalog and
|
||||
real HTTP boundary tests in `yoi-workspace-server`.
|
||||
実Workspace、account、Repository、Runtime、Workerは作成しない。拒否fixtureの診断を正常系の成功として扱わず、captureの終了状態だけで視覚面を承認しない。横断検証規則は [Visual Review](../../../../docs/development/ui-ux/visual-review.md) に従う。
|
||||
|
||||
Reference in New Issue
Block a user