Select a ready snapshot
Find the snapshot in the dashboard or callsm.snapshots.list(). Lists are paginated. Filter by the source environment or status when you know them, and follow nextCursor for the remaining results.
Read the snapshot by ID before a run if you do not know its status. Only status ready can start a new environment. A snapshot in saving needs more time. A failed or deleted snapshot needs a replacement.
Rename a snapshot with sm.snapshots.update(id, { name }). Pass name: null to clear the name. A rename does not change its ID or data.
Use names to describe fixture intent, such as an account with an open opportunity. Keep the snapshot ID in your test configuration so a renamed snapshot does not change which fixture your run selects.
Create an isolated copy
Callsm.environments.create({ snapshotId }) in place of a create call with apps. The snapshot supplies the saved app names, versions, settings, and data, even if the current default version has changed. Creation does not accept app overrides alongside snapshotId. The saved versions stay published while a snapshot that is not deleted uses them, so a ready snapshot keeps starting environments after a newer default version is published.
The caller needs environments:write and snapshots:read. The snapshot must be in the new environment’s workspace.
Wait for running, request credentials, run the test, and delete it in finally.
The complete snapshot example shows creation, restoration, verification, and cleanup together. The test helper shows how to keep cleanup with the code that creates an environment.
Refresh a fixture
To change a fixture, create an environment from the existing snapshot, write the new records, and create a new snapshot. Update the test configuration to the new snapshot ID after checking the resulting data. Existing snapshots do not change when restored environments are edited. If a test sees different records than expected, check the snapshot ID, app name, and actor before changing its query. See data troubleshooting.Inspect the saved fixture
sm.snapshots.get(id) returns the source environmentId, workspace, status, name, creator, and timestamps. apps identifies each saved app by its name, appId, version, and versionId. sizeBytes on the snapshot and its apps is null until the size is known.
createdAt records acceptance. readyAt records when the save finished. A failed snapshot has a failure code and message. Creating an environment from it fails with invalid_status.
Delete a ready or failed snapshot with sm.snapshots.delete(id) when no future runs need it. Deletion marks the snapshot deleted and prevents new environments from using it. Environments already created from it keep their own data. File cleanup can finish later. A saving snapshot rejects deletion with invalid_status. Wait until the save is ready or failed before you delete it. Snapshot listing omits deleted entries unless the status filter includes them.