Create a Scenario and test the behavior it measures¶

A Scenario defines a test, its expected behavior, and the Runners that may execute it. Start with a small read-only check. Test it from your development environment, then trigger a recorded run from the intended Worker location. These are different network perspectives.

This guide assumes an existing project and an active, authorized Runner with a compatible Worker. Follow the quick start to create that setup. The tools use the configured default control plane at https://urth.example.org; see Installation for another endpoint.

1. State the outcome and choose a probe type¶

For example: the public health endpoint returns HTTP 200 within the probe's five-second deadline. That checks one response. It does not prove that a customer can sign in or complete a purchase. Use a workflow test when that is the outcome you need to verify.

Probe kind	Use it to test
`http`	HTTP status, headers, or response content from an endpoint.
`tcp`	Connection establishment and supported request/response exchanges.
`dns`	DNS resolution and expected records.
`icmp`	Network reachability, with the required host permissions.
`grpc`	A gRPC health check.
`rest`	A sequence of requests defined in a `.http` or `.rest` script.
`har`	Replay of HTTP traffic captured in a HAR file.
`puppeteer`	A browser workflow implemented in a JavaScript script.

Select a kind supported by both your CLI build and the intended Workers. Browser probes need a compatible runtime and browser. Native Worker images and snaps do not provide browser support. Python browser execution (pypuppeteer) is not implemented in the inspected source; do not select it for this procedure. A HAR file can contain credentials. Review it before using or sharing it.

The Runner must permit the chosen kind in spec.jobRequirements.probeKinds. Admitted Workers must support all kinds allowed on that channel. Ask the Runner operator to review its policy if the required kind is unavailable.

2. Define the Scenario¶

Save this complete manifest as scenario.yaml. Replace the target with an endpoint you are authorized to test. The location: lab selector assumes the Runner from the quick start:

apiVersion: urth.sre-norns.com/v1
kind: scenarios
metadata:
  name: service-http-lab
spec:
  active: true
  description: Expect HTTP 200 from the lab network
  requirements:
    matchLabels:
      location: lab
  prob:
    kind: http
    timeout: 5s
    spec:
      target: https://service.example.org/health
      http:
        method: GET
        valid_status_codes: [200]
        preferred_ip_protocol: ip4
        ip_protocol_fallback: true

Use a descriptive name and define the response you expect. This example explicitly requests HTTP 200 and prefers IPv4 with address-family fallback. Choose an address-family policy that matches what you intend to measure. The prob field contains the test body. requirements selects a Runner; it does not provide routes, target credentials, or access permissions.

For an HTTP body assertion, you can add fail_if_body_not_matches_regexp under http. For example, ['"status"\s*:\s*"ok"'] requires matching response text. This is a text match, not a parsed JSON assertion. Use a request script or browser workflow when the test needs more detailed application checks.

Leave the schedule empty for manual testing. Recurring execution is not implemented yet. Keep secrets out of manifests intended for source control or the public preview.

3. Test locally before saving it¶

Create a private working directory and run the file:

install -d -m 700 ./worker
urthctl run -f scenario.yaml --runner.working-directory=./worker --runner.timeout=5s

Read the probe log and the final script finished result. Edit the definition and repeat until it tests the intended behavior. A failed probe can still return a zero process exit status in the current implementation; do not infer probe success from the shell exit code alone.

The probe runs on the machine where you invoke urthctl. That machine may not have access to a private target. A failure can therefore reflect local DNS, routing, credentials, or TLS trust rather than a Scenario defect. Use the local troubleshooting guide to test from a suitable jump host. Local runs do not add Results or Artifacts to server history.

4. Save the definition and run it through a Worker¶

Sign in and select your project:

urthctl auth login
urthctl context use PROJECT
urthctl apply scenario.yaml
urthctl trigger service-http-lab
urthctl get results service-http-lab

Replace PROJECT with your project's name or ID. apply saves the definition. trigger creates a recorded run for an authorized Worker. It does not execute the probe on your CLI machine.

In the UI, open the project and select Scenarios → service-http-lab. Check Eligible runners and Ready workers. If placement is unavailable, check Runner authorization, active state, labels, and probe policy. Inspect the completed run's executor, status, logs, and available artifacts.

Compare the recorded run with the local test. A local success does not prove that the Worker has the same network path, credentials, trust store, or runtime. Use Run scenarios locally to investigate a difference.

Create and test through the web interface¶

You can create the same Scenario without authoring a complete manifest:

Open your project and select Scenarios → Create scenario.
Enter the Scenario name and description.
Set Scheduling to Enabled so manual runs are permitted.
Leave Schedule empty.
Select http in Probe kind.
Set Timeout (seconds) to 5.

Enter the following in Probe specification (YAML):

target: https://service.example.org/health
http:
  method: GET
  valid_status_codes: [200]
  preferred_ip_protocol: ip4
  ip_protocol_fallback: true

Enter the following in Runner requirements (YAML):
```
matchLabels:
  location: lab
```
Save the form.
Check the placement information on the detail page.
Select Run now and inspect the recorded run.

For another kind, supply its probe-specific fields or script body in the probe specification. The form accepts the contents of prob.spec, not an entire Scenario manifest. Run now executes through the Worker fleet. For a local test of the saved definition, use urthctl run service-http-lab.

Revise an existing Scenario¶

Open Edit scenario in the UI, or export the current manifest:

urthctl get scenario service-http-lab -o yaml > scenario.yaml

Edit the exported file. Test it locally, then apply and trigger it again. Keep the exported resource version so a concurrent change is refused. A Scenario edit does not rewrite input already captured for an existing job.