[Hackathon] Add "test export" / "test import" to round-trip test DEFINITIONS for version control

[Andy00L]

Discord Username / User ID

interferon0

What does this improvement do?

There is no way to get a test's definition out of (or back into) TestSprite as a file, so test definitions cannot be version-controlled, reviewed in PRs, backed up, or migrated — the tests-as-code model that made Checkly and Terraform sticky. Add test export [--out ]: compose the existing GET /tests/{id} (metadata) + GET /tests/{id}/code into one deterministic .testsprite.json (stable key order, a schemaVersion, and the codeVersion recorded as provenance). Add test import : create (POST /tests) or update (PUT /tests/{id} + PUT .../code, honoring the existing codeVersion optimistic-concurrency guard) from that file. Note: this is DEFINITION export, distinct from the filed JUnit RESULTS export (#95) — different artifact, different purpose.

Details / implementation notes

Honest limitation disclosed up front: backend tests round-trip losslessly (metadata + Python code), but a frontend test's authored planSteps[] is write-only on the wire (PUT /tests/{id}/plan-steps exists; there is no GET, and GET /tests/{id} returns only planStepCount) — so FE export carries metadata + generated code with an explicit planUnavailable: true marker instead of silently dropping the plan. If that gap matters to reviewers, v1 can be scoped to backend tests. Reuses the existing create/update/code-put request shapes and idempotency-key minting; file writes honor the existing --out safety guards. No new dependency. Natural follow-up (separate issue): a declarative sync

reconcile. PR to follow once assigned.

Confirmations

• I have searched existing issues and this is not a duplicate.
• I have provided my Discord identity above for reward coordination.

[zeshi-du]

Triage: deferred — this is the one proposal that collides with in-flight server-side schema work (unified test entity + real code versioning). Freezing a .testsprite.json schema now would guarantee a breaking rev, and as you disclosed, FE plans are write-only on the wire today so exports would be structurally lossy. We do want tests-as-code eventually; parking until the schema settles.

[Andy00L]

/assign

[testsprite-hob]

Assigned to @Andy00L. Thanks for taking this on. ⚠️ You're now over the soft 3-issue limit (5/3). Consider finishing one before taking more.

Your open assigned issues (5/3):

• [Hackathon] Validate API responses at runtime with valibot instead of blind casts #102 — [Hackathon] Validate API responses at runtime with valibot instead of blind casts
• [Hackathon] Read ~/.testsprite/config for persistent defaults (output, endpoint, project) #100 — [Hackathon] Read ~/.testsprite/config for persistent defaults (output, endpoint, project)
• [Hackathon] Add "testsprite ci": one-shot run + gate + GitHub-native output #99 — [Hackathon] Add "testsprite ci": one-shot run + gate + GitHub-native output
• [Hackathon] TESTSPRITE_PROJECT_ID env default for --project #76 — [Hackathon] TESTSPRITE_PROJECT_ID env default for --project

[zeshi-du]

I owe this issue a decision — I said on 07-23 that I'd record whether the 07-03 deferral was lifted, and didn't. Meanwhile @Andy00L fixed all five review defects on #265 and has been waiting 19 days on silence. Sorry.

Why it was deferred: an export format for test definitions would freeze a test-entity shape we were actively changing, and shipping a file format is a much harder thing to walk back than a flag.

What's changed since: the unified schema is live, and the CLI already has the pieces this would serialise — test get, test plan put, test code get/put — so an export format can be expressed in terms of the existing wire types rather than inventing a parallel one. That removes most of the original objection.

What I still want to be careful about, and what the PR review will focus on:

• The exported artifact must be a projection of the API's shapes, not a new schema with its own versioning story. If it needs a formatVersion field, that's a signal we're inventing a format rather than serialising one.
• Round-tripping must be lossless or explicitly lossy — silently dropping a field on import is the failure mode that makes version-controlled definitions untrustworthy.
• This is not a suite/grouping file. Test Lists are the product's suite concept and the CLI should adopt those rather than grow a parallel one; export/import is about putting individual definitions under version control, which is a different thing and is in scope.

Decision: the deferral is lifted, subject to those three constraints being met in review. @Andy00L — #265 needs a rebase (main has moved two releases) and one more look at whether the import path can reuse the readSecretFileGuarded() helper that just landed. Do that and I'll review it properly, on a real timeline this time.

I'm flagging this as my call rather than a settled team position, so if it turns out to conflict with in-flight platform work I'll say so here rather than silently re-parking it.