Creating & Editing Specs

This page covers how a spec actually gets created and changed day to day. For the spec format itself (front matter, cases, Liquid), see Writing a Spec.

	Standalone	Connected
Create a spec	"New Spec" button, in-app editor	Add a .md file to the repo
Edit a spec	Open it, edit, save	Edit the file locally, commit, push
Preview	Live Preview tab in the editor	No in-app preview — see Desktop Preview
History	Version History dialog: the last 50 versions, each restorable	Your repo's own git history

Standalone

Creating a spec

Click New Spec. The form has a Folder field (optional — see Organizing into folders below) and a content editor. Your spec's <H1> title is what Testspace uses to derive its internal identity — see Renaming vs. moving below for what that means in practice. Click SUBMIT, and the spec exists immediately — no separate publish step.

You don't type the spec's front matter: the editor adds it when you submit. When copying a spec from a repository, paste only its body (from the # title down) and set its variables in the Variables box; a pasted front matter block stays in the body. A typo in the front matter's YAML turns the spec off (Disabled) without an error, so check the spec still runs after editing variables. A spec can't be saved without an <H1> title, or with two cases of the same name (see Writing a Spec).

Editor toolbar

The spec editor and the include editor share one toolbar:

• Formatting: heading (aA), bold, italic, blockquote, code, link, bulleted and numbered lists, and To-Do (a checklist step).
• Include: opens the Insert Include menu, listing the Space's includes with their descriptions; picking one inserts its {% include %} tag (see Includes).
• Variable: opens the Insert Variable menu: your spec's own variables under Custom (this spec), then the global variables. Picking one inserts its {{ }} reference.
• If: wraps the selected text in an example condition, {% if space.name == 'main' %} … {% endif %}, for you to edit.
• Tabs, Note, Warning, Collapse: insert a starting skeleton for each presentational tag.

Above the spec editor, the Variables box (labeled Variable (N) once the spec has some) expands to show the spec's front matter (without the testspace: line), where you can type custom variables and automated fixtures directly, one name: value per line. Manage, next to it, opens the Manage Variables popover to add, edit and delete custom variables without typing YAML.

To attach a file, drag and drop, select, or paste it into the editor: it's uploaded and a Markdown link is inserted (an image reference, for an image).

Live Preview

The editor has Write and Preview tabs. Preview renders Liquid for real: variables resolve, {% include %} pulls in actual include content, conditionals and loops run — it's exactly what a tester will see, not a raw-markdown guess. If you're previewing something that depends on a value normally supplied at run time (like an include being tried on its own), an unresolved field shows up as a visible {{ spec.foo }} placeholder rather than silently rendering blank, so a preview gap is obvious rather than looking like the real thing is broken.

Use Preview before you save — it's the fastest way to catch a Liquid mistake or a bad include reference before it ever reaches a Test Session.

Organizing into folders

The New Spec form's Folder field is optional and only shown at creation. A spec with a folder set appears under that folder's own tab in the left nav, alongside ·Overall· (everything) and No folder (everything without one).

Editing, saving, and moving

Choose Edit from the spec row's options menu (☰) and edit its content directly. Saving supports an optional Edit message — a short note about what changed, shown later in that spec's version history.

Editing content never moves a spec between folders, even if you change the title — to relocate an existing spec, use Move from the spec row's options menu, which opens a small dialog with just a Folder field.

The Specs list's Updated column shows when each spec was last changed, with its version and who changed it (v3 · Jane Smith).

Renaming vs. moving

Changing a spec's <H1> title is always safe — Testspace tracks a spec by an identifier assigned once, at creation, so renaming later doesn't break anything referencing it. Moving a spec to a different folder is a separate, explicit action (above) — editing content alone never does it.

Cases are different: Testspace matches a case to its history by name, so renaming or removing a case (an <H2>) loses its history and retires its tracked failures at the next session that includes the spec (Failure Tracking).

When a spec won't parse

A spec with a structural error, or one referencing a missing include, can't be selected into a test session at all — it shows a red error indicator in place of its checkbox, both in the Specs list and in session-selection dialogs. This is by design: broken specs are caught before a session starts, not mid-run. Preview (above) is how you catch this while you're still writing.

Version history

Choose History from a spec row's options menu to open its Version History dialog. Every save creates a new entry (duplicating and merging a space do too), and the last 50 versions are kept. Each entry shows its Edit message, who saved it and when, and its lines added and removed (+/−); click that count to see the diff. Restore on a past version creates a new version with that content, so no history is lost.

A spec changed on both sides of a Space merge is marked as a merge conflict; see Resolving merge conflicts.

Deleting a spec

Choose Delete from a spec row's options menu. Deleting can't be undone, and the spec's tracked failures are retired at the next session (Failure Tracking).

Connected

A Connected spec's canonical content lives in your repo, not in Testspace — you edit it with your own tools and it reaches Testspace through your normal git workflow.

Adding or changing a spec

Add or edit a .md file under your project's specs folder (specs/ by default — see Manual Spaces) and commit and push as usual. Testspace picks up the change automatically. To disable or remove a spec without deleting the file, see Front Matter. Deleting or removing a spec retires its tracked failures at the next session. Moving a spec is just moving the file — git mv, like anything else in the repo.

Previewing before you commit

There's no live in-app preview for a Connected spec. Desktop Preview covers using Jekyll locally to render specs before you push.

History

A Connected spec's history is your repo's own — commits, blame, pull requests. There's no separate Testspace-side version history dialog for Connected specs the way there is for Standalone.