Override Surfaces

A live Test Plan run lets you inject values at three independent
scopes: the whole plan, a single pending item, or a single step
inside a TCM case. All three can be active on the same run; the runner
resolves the most specific one when it builds each step’s request.

This page is the focused reference for those three scopes — when each
locks, what wins when they fight, and how to drive them from the UI.

About URLs in examples: all examples use localhost:5770 as the
default Mockarty address. If your instance runs on a remote server,
replace localhost:5770 with its actual address.

Related pages: Run View ·
Plan Run Report ·
Test Case Steps ·
Runtime Flow View (test case)

The three scopes at a glance

The three scopes do not overlap — they’re independent layers — but
when the runner resolves a {{plan.X}} reference inside a step, it
applies a precedence rule documented below.

Plan-level context override

This is the “type a value at the top of the page” flow. The Run View
header has a button Override context.

Clicking it opens a drawer with two fields per row:

• Key — the name under plan., e.g. auth_token or customer_id.
• Value — the value the runner will substitute when a downstream
  step writes {{plan.auth_token}}.

You can add multiple rows; the drawer batches them into a single
save so the audit trail records the override as one event.

What the runner does with your override

The runner merges your keys into the run’s plan-context bag. Every
TCM case item that starts AFTER the merge sees the new value when
it builds its request. Two important details:

• A case that is already running keeps its already-merged snap.
  Last-write-wins on a mid-flight step would be too dangerous — the
  step has already resolved its bindings. But the Run View shows a
  small banner on the running case: “if you rerun step N from here,
  it’ll use the new value”.
• Already-completed steps don’t change. The merge is forward-
  looking, never retroactive.

When the override locks

You can apply a plan-level override at any time while the run is
in flight. The runner refuses the override (HTTP 409 from the
endpoint, “plan run is terminal” toast in the UI) once the run
reaches a terminal status — passed / failed / cancelled. To replay a
scenario from a finished run with the same values, use Rerun plan
with the Preserve overrides checkbox ticked.

Key and value rules

• Keys must match [A-Za-z_][A-Za-z0-9_.]{0,127} — letters,
  digits, underscore, and dot, starting with a letter or underscore,
  up to 128 characters. The drawer shows the rule live as you type.
• String values are bounded in size; the drawer rejects oversized
  blobs with an inline hint pointing at the limit.
• A single drawer save can contain up to several dozen keys —
  comfortably more than you’ll need in one push.
• The endpoint is rate-limited per user (you’ll see a “slow down”
  toast on hammer-clicking). The budget is shared with the case-
  step /run-extract from the standalone case view.

Item-level parameter override

This is the “edit the parameters of a pending item before it starts”
flow. The Run View shows an Edit parameters action on every
pending item card.

Clicking it opens a drawer with a JSON editor pre-filled with the
item’s current parameters. Edit the values, save, and the
orchestrator picks the new shape up when it dispatches the item.

What you’d typically change

When the override locks

Item-level overrides apply only while the item is in pending
status. Once the item starts running you can no longer change its
parameters; the orchestrator has already snapshotted them. To clear
or replace an override after the item ran, use Rerun item to
reset it to pending, then edit the parameters again before the next
dispatch.

The override is wiped on item rerun (so a second-attempt parameter
change is always a deliberate user act). The plan template itself is
never modified — future runs of the same plan start from the saved
parameters.

Step-level override (TCM only)

This is the per-step /run-extract flow inside a TCM case — covered
in detail on Test Case Steps §5.
Briefly:

• Open a TCM case item in the Run View; the case’s flow tree is
  inline.
• Click a step → its drawer opens.
• The drawer has a small Add extract button that lets you write
  a single plan.X = value pair scoped to that case run.

The step-level override lives on tcm_case_step_runs and is wiped
on step rerun. It does not propagate up to the parent plan; it stays
inside the case. If you want the value to be visible across other
items in the plan, lift it up via the plan-level drawer instead.

Precedence — which value wins

When a step builds its request and encounters a {{plan.X}}
reference, the runner picks the most specific value. The order, from
most specific to least:

case-step run-extract
> case-author default in plan_context_snap
> plan-level run override
> empty (substitution fails — runner logs a missing-binding warning)

For environment / secret precedence inside a step, see
Test Case Steps §4.

Worked example

Plan run with auth_token = "T0" set by the plan-level drawer.

• Case A starts. Its first step is Login, which extracts
  auth_token from the login response into plan.auth_token. At
  the moment of extraction the value becomes T1 for the rest of
  Case A — the step-level extract wins.
• Case A’s later step GET /me uses {{plan.auth_token}} — it gets
  T1.
• Case B starts AFTER Case A finished. Case B has not extracted
  auth_token itself. Its first step sees T0 (the plan-level
  override, because no step-level extract has overwritten it yet
  inside Case B).
• The user opens the drawer and writes auth_token = "T2". Case A
  is already terminal — nothing changes there. Case C, which starts
  after the drawer save, sees T2.

UI walkthrough

[Override surfaces — three drawers — screenshot pending]

1. Plan-level drawer — header Override context button on the
   Run View. Opens a list of key/value rows; save commits all rows
   at once.
2. Item-level drawer — Edit parameters action on any pending
   item card. Opens a JSON editor; save commits the new parameters.
3. Step-level drawer — click a step inside an expanded TCM case
   item; the step drawer has an Add extract button (TCM scope).

All three drawers are auditable: the plan-level and
item-level overrides write an audit-log row keyed on the run id
and the actor, so a compliance review can see who patched what when.
Step-level extracts are recorded on the case run alongside the
authoring extracts so the trail is complete.

Common pitfalls

• “Cannot override — item is running” — once an item starts,
  parameters are locked. Rerun the item to drop it back to pending,
  then edit.
• “Plan run is terminal” — the run already finished. Use
  Rerun plan with Preserve overrides instead.
• A new key isn’t being read — {{plan.foo}} references in a
  TCM case work only after the case starts. Cases that started
  before your override see the old value (or no value); cases that
  start after see the new one. Re-rerun the case if you need the
  new value.
• “Invalid key” — keys must start with a letter or underscore,
  contain only [A-Za-z0-9_.], and not exceed 128 characters. The
  drawer surfaces the failing rule.
• “Value too large” — string values are bounded. Trim, or store
  the heavy payload in a step’s attachment and reference the
  attachment URL instead.
• Rate limited — the per-user budget is intentional to keep the
  audit trail readable. Batch keys into a single drawer save.

Permissions

• Plan-level override: test_plan:write on the run’s namespace.
• Item-level override: test_plan:write.
• Step-level extract: test_plan:write (the underlying
  case-run endpoint shares the gate).
• Reading the current overrides log is open to anyone with
  test_plan:read on the namespace.

Next: the Run View page covers how
the live page renders these overrides. The
Plan Run Report page covers how they
surface in the exports (with redaction).