Skip to main content
A reference video illustrates a workflow definition. It is distinct from a finding’s evidence video and a runner’s replay recording. Uploading a reference clip does not execute a test or certify the behavior.

​
Attach a useful clip

Open a workflow and use its reference-video controls. Choose a small MP4 or WebM that demonstrates the saved-view interaction with synthetic data. Supply a meaningful title and context/note where the UI offers them. Explain what the viewer should inspect, rather than relying on a clip alone to define the expected result. Upload limits, allowed MIME types and deployment capabilities come from the running server. Local uploads use private filesystem storage; hosted uploads use private R2 with staged/resumable transfers. Do not manually construct large base64 requests or expose storage credentials.

​
Handle interrupted uploads

Keep the workflow and upload draft open while the client handles chunk/status/complete operations. A completed staged upload still needs the final association commit. If expectations changed while the upload was in progress, reread the workflow and reconcile; do not force an old expected version onto newer text. Expired or invalid transfers need a fresh upload.

​
Edit, replace or detach

Metadata edits, replacements and detachments create saved history rather than rewriting earlier attachments. Confirm replacement/detachment carefully. A failed operation preserves the draft so you can retry after resolving the error. Use the same request identity/content after an ambiguous commit. Select a historical definition to see that version’s association and metadata. A text-only expectation edit keeps the clip’s original illustrated definition, so the UI can label it Earlier expectations. A detached current clip can still be playable from the exact earlier definition. Historical views are read-only. Archiving a workflow or ancestor makes it inactive, while saved history remains available under deployment authorization. Do not infer an indefinite media retention policy from history support; operators own backup and retention. Developers extending uploads should use the video history contract and apps/shared/catalog-videos.ts, rather than inventing transfer endpoints or bypassing optimistic concurrency.