Test Management: Trash, History, Attachments & Run Reports

Deleting a case — Delete in the bulk bar of Test cases, Delete in the Editor’s More menu, or DELETE /api/tests/{filename} — moves the YAML into tests/cases/.trash/ instead of unlinking it. A sidecar <filename>.meta.json records test_id, title, deleted_by, deleted_at and an optional reason, and the event is written to the case’s history as deleted with the account that did it.

The case list only globs *.yaml at the top level, so a trashed case leaves the UI immediately while staying whole on disk.

Trash (N) in the Library menu of the Test cases header switches the list to the trashed rows — Case | Title | Deleted by | When | Reason — each offering Restore and Purge; the view’s own header has Refresh and, for admins, Empty trash. The menu item is offered to every account: the restore and purge buttons inside the view carry their own gate, and hiding the way in would hide that a delete is undoable.

A purge is the only step that removes anything permanently, and it removes everything the case had: the YAML, its sidecar, .attachments/<stem>/, .history/<filename>/, the case_history rows and the case_meta row that recorded who created and last edited it. That completeness is the point — a case later created under the same filename starts its history at version 1 rather than inheriting the numbering of the case that is gone.

Each removal is defended separately and none of them is fatal: a directory the name validator will not vouch for is left alone and logged, and a file the OS refuses to delete is logged rather than raised — a purge that half-succeeded is reported, never a 500 over a case that is already gone.

Copy on a case row of Test cases (it appears on hover, beside the pencil) and Duplicate in the Editor’s More menu both post POST /api/tests/{filename}/duplicate. The body takes an optional {id?, title?}; neither button sends one, so from the UI you always get the generated pair below. A copy is the original verbatim except for three things:

Attachments are copied with it, into the new case’s own directory. The new file opens its history with a created entry whose change line reads duplicated from <file>. An id or a filename that already exists answers 409, and the filename the new id would produce is validated before it is ever joined to the corpus directory.

Tick rows on Test cases and choose Find / replace… from the bulk bar. The modal previews every before/after in a table before anything is written: Preview runs the call with dry_run (its default) and only then does Apply light up, which repeats the call with dry_run: false behind a confirmation naming the field and the number of cases. dry_run defaults to true on the endpoint too, so the preview is the default and the write is the deliberate second step.

The modal only ever sends mode: replace. The other mode has its own button: Set section… in the same bar asks for one value and writes it onto every ticked case (mode: set, dry_run: false) — there is nothing to preview when the "after" is the value you just typed.

POST /api/tests/bulk-update:

The answer is {changed, unchanged, errors, dry_run, items:[{file, before, after, changed, error?}]}; unchanged counts the files that were read and left alone, while a file that could not be read at all is an error, not a decision to skip it. Each written file records an edited history entry whose change line names the field, e.g. title: OIT ACS login → CPE Admin login, and an empty value renders as (none). Setting project registers the project first (the same ensure_project an import uses). The filename never changes — a bulk rename edits titles, not files.

Editor Save and New, Upload, bulk update, duplicate, restore-from-trash, restore-from-version, XML import, TestRail import and re-import all go through one recorder, so the history is complete whichever of those buttons produced the change.

A version is a number plus a full snapshot of the file as it was written. Snapshots live in tests/cases/.history/<filename>/v<N>.yaml.

The Editor’s Change history panel lists, newest first: version, action, who, when, the changed fields, the case’s Jira reference (rendered as a link) and the portal build the change was made against. Two actions per row, both offered only while the row still has its snapshot:

The change lines are computed by comparing the two parsed cases, not the two texts: title, section, project, portal, preconditions, metadata.references / priority / type, emulator_setup, and the steps (steps: 12 → 13, step 4 changed, at most ten step numbers listed). A file that cannot be parsed on either side records content changed; two files that differ in nothing the recorder tracks record no visible change.

Numbering is taken under a process-wide lock: two saves of one case arriving together cannot both claim the same version and overwrite each other’s snapshot. A snapshot that cannot be written is logged and the version row is still recorded — the row then carries no snapshot, and its Diff and Restore buttons are not offered.

A case can carry files: the device tree it was written against, a screenshot of the expectation, an extract from a spec. They live in tests/cases/.attachments/<filename stem>/, outside the glob the case list walks — attaching a file never adds a field or a step to the YAML.

The Editor’s Attachments panel lists, uploads, downloads and deletes them, showing each file’s size and uploader, and offers .xml files a one-click Use as tree button that uploads the file through POST /api/trees/upload and writes its name into the form’s tree_file. It needs an Emulator Setup block to write into, and it only fills the form — Save the case to keep it.

Limits: 20 MB per file; the stored name is the basename with anything outside A-Za-z0-9.- folded to , so a browser sending a full Windows path and a caller trying to climb out of the directory both end up with a plain name. Uploading the same name again replaces the file and says so (replaced: true). Viewers may read attachments; only admins and editors may upload or delete.

Trashing a case and restoring it leave the attachment directory exactly where it is — while the case sits in the trash the attachment routes answer 404 (there is no such case), and a restore makes them readable again. Purging the case is what removes the files.

TestRail’s own XML cannot carry an executable step, so the agent exports its own lossless format: one <test_case> element per case, with the whole YAML as the text of its <yaml> element. The text is XML-escaped on the way out (&, < and > become entities) and unescaped on the way back in, so the round trip is byte-exact and no CDATA section is involved.

Attachments are binary and stay out of the XML; the answer names the cases that had some so you know what did not travel. An import writes live files only — it never empties the trash, so an export/delete/import cycle leaves the trashed copies in place.

Every batch stamps the portal it ran against, and the two values fill the Build and Version columns of the export and the header of the report.

They come from POST {base_url}/iot-webservice/iotw/System/information with an empty body — the call needs no token and answers e.g. {"appVersion": "7.1.1 Build master_7.1.2.RC"}, which is split on " Build " into portal_version (7.1.1) and portal_build (master_7.1.2.RC). A shape that does not split reports the whole string as the version rather than dropping what was known. The answer is cached for 10 minutes per base URL with a 3-second timeout, and any failure caches an empty answer just as a success is cached, so a stand that is down costs one connect attempt per TTL rather than one per run: the stamp never delays or blocks a run.

The probe is skipped entirely when FT_PORTAL_VERSION_PROBE=0 — no unit test may dial a stand. A case edit reads the cache and never dials, because three of the four case-write endpoints are async, and a synchronous probe on the event loop would stall every other request for as long as the portal took to answer; an edit made on a server that has never run against the stand therefore records no build rather than delaying the save to learn one.

Nothing on this page adds a field to a case YAML or a step to a test. The side data sits next to the corpus, in directories the *.yaml glob never sees: