Export QualityMax with QTML

QTML (Quality Testing Meta Language) is QualityMax’s text representation for contracts, personas, fixtures, and test intent. It provides a reviewable portability artifact for a project or selected test cases. QTML import and export are currently a preview limited to QualityMax owner accounts.

Export a project

When QTML is enabled for your owner account:

1. Open QTML in the authenticated QualityMax application.
2. Choose Export, select a project, and optionally limit the export to selected test cases.
3. Generate the document, review it in the editor, and download the .qtml or .qtml.json file.
4. Store the file in an approved repository or archive and record the export date and source project.

Before: project intent

workspace_name: Storefront
base_url: https://staging.example.com
test_case:
  name: A shopper completes checkout
  given: A product is in the cart
  when: The shopper submits payment
  then: An order confirmation is shown

After: portable QTML

QTML/1.0
contract Storefront @app("https://staging.example.com") {
  context {
    domain: commerce
    risk: medium
  }
  intent complete_checkout {
    describe: "A shopper completes checkout"
    type: e2e
    given: A product is in the cart
    when: The shopper submits payment
    then: An order confirmation is shown
  }
}

Compatibility and preservation

The reference specification draft is QTML v0.1, the text header is QTML/1.0, and the canonical qtml-lang implementation release for this interchange contract is 0.1.2. These are separate version identifiers, not a new language major. The reference implementation and editor live in Quality-Max/qtml.

Surface	Supported	Preserved but not executable	Rejected or limited
Web import/export	All contracts with intents, Context, structured assertions, constraints, variations, personas, fixtures and metadata	Optional extensions and document metadata retained with each case	Unknown required fields/features, malformed syntax, unsupported schema/profile; contracts without intents cannot be stored
Lossless JSON transport	qtml-interchange/1 schema with qtml/1.0 profile and modeled document AST	Nested values the legacy text generator cannot render	Unknown AST fields and duplicate JSON keys; nonfinite numbers
Reference CLI/editor/LSP	Legacy line-oriented text	No guarantee that legacy formatting preserves every AST field	Use qtml.interchange.decode/encode for archival roundtrips; older text-only readers cannot read JSON interchange
Mobile flows	Existing qtml-mobile/1 mobile reader	Separate mobile flow representation	No implicit web/mobile conversion; web import rejects this profile
Playwright generation	Model-assisted generation from intent	Constraints and metadata supplied as context do not prove generated behavior	Not deterministic compilation or a guarantee that every preserved feature executes

Export chooses .qtml text only when decoding the generated text reproduces the complete AST. Otherwise download the .qtml.json artifact with its returned JSON media type. Do not rename JSON to .qtml for an old text-only editor. Comments and indentation are not preserved; expression contents and AST list order are significant.

Consumers negotiate schema, profile, and required_features before import. Supported preservation feature labels are context, contracts, constraints, variations, metadata, and assertions. Optional vendor data belongs in the JSON extensions object. Unknown required features fail with an actionable error rather than being discarded. Line numbers are returned when available; complete source maps and column ranges are not promised.

Durable storage and partial imports

Each imported test case retains its structured intent, contract, document metadata and import grouping. Export includes only surviving selected cases: deleting a case or choosing an empty selection does not restore it from the original document. Separate imports with the same names remain separate contracts. Imports with incompatible document metadata must be exported separately. Ordinary edits to steps and expected results are reflected on export; edits to flattened structured-constraint prose require an explicit structured QTML update.

Import is not atomic. The response includes contract_results and per-intent outcomes, saved case IDs, and imported, partial, or failed status. Saved siblings remain durable when another write fails. Keep the receipt and retry only failed intents after resolving the reported issue; retrying the full document creates duplicates.

The nullable qtml_semantics storage migration must be applied before deploying this reader/writer. Existing cases remain readable with no envelope. Missing storage support fails an import rather than silently downgrading it. Rollback readers may still show ordinary fields but cannot promise lossless export; retain the envelope and original artifacts.

Identity and generation

Parsing an exported document or importing a document returns a versioned qtml-semantic/1:sha256: digest covering every modeled semantic field and optional transport metadata. Changes to assertions, constraints or Context change identity; comments and indentation do not. Legacy contract and intent hashes remain lookup aliases because they omit some semantics. Neither digest nor alias grants authorization or proves generated code matches intent.

The MCP convert_qtml_to_playwright operation imports and persists test cases before invoking model-assisted code generation. It is a write operation with persistence side effects, including possible partial import outcomes. Review generated scripts and their tests before execution. Editor and integration clients must retain the returned transport format and metadata instead of passing lossless JSON through the old text formatter.

Prove the export is reusable

Use Validate and resolve every reported error. Then import the file into a disposable project and compare contract metadata, personas, fixtures, test-case names, steps, and expected outcomes. Keep Playwright, k6, or other executable scripts in version control as separate artifacts; a QTML intent document is not a substitute for every framework file or execution result.

Export-everything checklist

• Export each project and keep a manifest of project IDs, names, and export dates.
• Retain executable test repositories and their dependency lockfiles.
• Download execution reports and evidence required by your retention policy.
• Record integrations, schedules, environment configuration, custom fields, and access rules separately.
• Restore a sample .qtml file before treating the archive as complete.

QualityMax does not present QTML as a full account backup: users, credentials, billing, run history, binary artifacts, and third-party configuration are outside this text format. Contact support before an exit if contractual retention or bulk artifact delivery is required.

For TestRail-specific boundaries, read migrate TestRail to QualityMax. For project structure, see core concepts.