Docs / Optional Mapping Tests

Test and deploy a mapping safely

An 850 purchase order maps correctly today. Before editing that map, keep a small sample and the output you expect. The next time you change it, a saved test can tell you whether that behavior changed.

Try it without touching a live map

Open the Mapper demo, open Tips, and choose Keep a mapping working (optional) in the tutorial chapters. Close any active lesson first. This chapter uses a temporary map and synthetic purchase order. It runs the real mapping evaluator, but does not send EDI, deploy configuration, or save its practice cases to your workspace. Finishing or closing restores your original workspace. The first-map quickstart is still the best place to start if you have not written a map yet.

1. Save one useful example

1. Open an editable map and run a sample.For an incoming 850, load a representative X12 order and use Run map. For an outgoing map, choose your source document and parameters, then use Run transform. Inspect the business values before treating the result as correct.
2. Expand Saved test cases (optional).Choose Save latest Run as test. This captures the run's input, parameters or transaction selection, and exact output. It does not turn every sample file in Explorer into a test.
3. Review the data, then Save in draft.Give the case a useful name, such as “850 with two order lines.” Remove customer data and secrets from the input and expected output. Review captured parameters too; if they need changing, update the Run inputs and capture a new result. Confirm that the example is safe to keep in configuration history.

Saving a case changes only the draft. When you apply it later, its fixtures enter configuration history and any connected Git repository. Deleting it later does not erase older history. Public Mapper share links omit saved cases.

2. Check an edit against that example

Suppose the purchase-order number comes from ST->BEG(03). Reading ST->BEG(02) instead can still produce valid JSON, but puts the order-type code where the PO number belongs. In a practice draft, make that change and choose Run saved cases. The case should fail even though the map can execute.

Expand Compare exact text to see the first difference and both outputs. Restore the correct expression and rerun the case. Do not replace the expected output just to make a failure disappear: decide whether the new behavior is actually intended.

PASSED means the generated text exactly matched the saved expectation and any selected X12 validation passed. FAILED means at least one check failed. ERROR means execution or a requested check did not produce a usable result. Whitespace, line endings, order, and delimiters count. Validation and exact-output tests answer different questions; neither is a substitute for checking meaningful business values.

Also validate generated X12 (outgoing maps)

For an outgoing JSLT or XSLT case, select Review / edit → Also validate generated X12. ModernEDI uses the map's existing document type and X12 version, the same document preparation as outgoing preview/send, and the existing X12 validator. Document bodies receive a synthetic envelope for validation without changing the exact output you compare. Leave this off for partial fragments that are not intended to form a complete document. Nothing is sent.

For example, an expected invoice might itself omit a required field. Its exact-output comparison can pass while X12 validation fails. The editor and server evidence show those outcomes separately. Valid X12 still does not prove the business values are right or a partner accepted the document.

The optional validateX12: true case property is stored with the fixture in configuration and Git. Browser and API server verification use the same rules; the server checks the exact frozen syntax tree and retains only outcomes and hashes. Changing the option requires fresh verification, but does not by itself redeploy the mapping. Incoming maps do not need this option.

Add a few examples for important variations: several lines, an omitted optional address, or an outgoing parameter. Each map supports up to 10 cases, 65,536 characters per input or expected output, and 256 KiB for its complete case data.

3. Review the change, not just the green result

In your signed-in workspace, use Review & deploy when the draft is ready. Review the map source, settings, and any added, changed, or removed cases. A saved draft is not the live map. If another editor or repository changed the configuration, resolve the reported conflict and prepare a new review.

If you use scenarios, this review also shows affected conversations. A pass on an older binding describes that older configuration; it does not verify the new map. You do not need to create a scenario to review or deploy a mapping.

4. Optionally retain a server verification result

Choose Verify saved cases on server in the review. ModernEDI runs the cases from that exact reviewed configuration, not from a later editor draft. The retained result identifies the reviewed plan, source, cases, evaluator, and syntax tree. Reopening an unchanged review retrieves that result.

While the review is open, result status updates automatically, including after a temporary connection failure. A completed result is also rechecked for changed dependencies. These checks never rerun the cases or change the review you approved. If evidence becomes stale, prepare a new review and explicitly verify it again.

Ordinary Run and Run saved cases feedback stays in the editor session. Server verification is the optional durable record. It has a 30-second suite deadline, supports cancellation, and shares a workspace limit of one active verification and 30 starts per hour with API verification. The latest 200 results are retained for up to 90 days.

A pass checks the saved examples in the backend evaluator. It does not prove live runtime activation, AS2 delivery, partner acceptance, or a complete business conversation. Browser verification is not an automatic deployment gate. If a tested dependency changes or cannot be checked, the old result is labeled stale.

If you connect an external repository, its owner can separately enable saved-case checks before automatic imports. That option runs the same cases against the incoming configuration and holds an import unless they pass. Mapping-only authoring and ordinary browser deployment remain available without it.

5. Deploy, then check activation and history

Confirm the reviewed deployment when you are ready. Wait for runtime activation before expecting new traffic to use the map. Open Change history to inspect the operation, the saved configuration version, and any associated server test result. Use Download verification evidence if you need to retain that result independently.

Changing only cases does not republish the runtime mapping or refresh scenario bindings. Case inputs and expectations remain configuration source; execution results are separate evidence, not files written into your repository.

Choose the next benefit you need

Follow one complete worked example: the same PO0001 sample connects a mapping test, an optional order/invoice scenario, and exact configuration history.

Use a scenario to check whether related documents and acknowledgments form the right business conversation. Use external Git to synchronize applied configuration with your repository. For optional CI checks, the configuration runner verifies these same saved cases against a complete proposed configuration; an explicit --verification-run-id can require that exact passing result during apply.

The Integration API reference documents spec.regressionCases, and the generated case JSON Schema supports editor tooling. You can keep using the browser and stop at any point in this progression.