Tests overview¶

A test is a saved check of one external system, the target. Tests belong to the environment you are working in, and are grouped by category in the sidebar:

Sidebar	Test type	API `type`	What it checks
Authentication	OIDC WIF Client	`oidc_wif_client`	Your STS or token endpoint's handling of federated workload ID tokens
Authentication	Client Id/Secret	`client_credentials`	Your token endpoint's OAuth 2.0 client credentials grant
Identity	SCIM Client	`scim_client`	Your SCIM 2.0 service provider (`/scim/v2`)
SIEM	REST API Poll	`siem_rest_api_poll`	Your log or audit API, polled the way a SIEM does it

Each test type's page lists every field it supports. This page covers what all tests have in common.

Common fields¶

Every test form starts with a Details section and ends with Expected result and Schedule sections.

Details¶

Field	Key	Required	Default	Notes
Name	`name`	✅	—	Unique among tests of the same type in the environment.
Description	`description`		—	Up to 1000 characters.
Enabled	`enabled`		On	Disabled tests cannot be run: manually, by schedule or by the API. A disabled OIDC WIF Client test's issuer endpoints also return `404`.

Expected result¶

Field	Key	Default	Notes
The target should	`expected_outcome`	`success`	`success`: the target should accept the request (issue a token, accept the SCIM requests, return events). `rejection`: the target should refuse it. Use rejection for negative tests, such as a revoked client, a forged token or an invalid API key.
HTTP status	`expected_status`	—	Optional exact status (100–599). When blank, success expects any `2xx` (or the status the specification requires) and rejection expects any `4xx`.
Specification checks	`strict_spec_checks`	On	Also assert the specification's MUST-level details, such as `Cache-Control: no-store` on token responses or the SCIM error format. Turn it off for targets you know deviate in minor ways when you only care about the core behaviour.

Each test type adds its own expectations, such as an expected error code or token type.

Schedule¶

Field	Key	Default	Notes
Cron expression (UTC)	`schedule_cron`	—	Standard 5-field cron, evaluated in UTC. Runs must be at least 5 minutes apart.
Run on schedule	`schedule_enabled`	Off	Turns the schedule on or off without losing the expression.

See Scheduling.

Running a test¶

A run can be started in three ways. All three are recorded in the same Test Log.

Trigger	Started by	Shown as
`manual`	Run now on the test page	Your name
`api`	`POST /api/v1/environments/{env}/tests/{test}/runs`	The service account
`schedule`	The test's cron schedule	System

A test can only run if it is Enabled and your tenant's subscription allows access (see Plans and billing).

Run statuses¶

Status	Meaning
`queued`	Waiting for a worker.
`running`	Helena is talking to the target.
`passed`	At least one assertion was checked and all of them passed.
`failed`	At least one assertion failed. The target did not behave as expected.
`error`	The run could not complete: a missing secret, a blocked URL, a connection failure, a timeout, or the test was deleted mid-run. Fix the configuration or the target's availability rather than its behaviour.

How Helena reaches your target¶

All test types send requests through the same outbound rules:

Public HTTPS only. URLs must use https:// and resolve to a public IP address. Private (10.x, 192.168.x, …), loopback, link-local and reserved addresses are refused, as are URLs that contain a username or password.
No redirects. A 3xx response is recorded as it is and never followed. Point the test at the final URL.
Timeout. Each request has a 15-second timeout.
Pinned connection. Helena connects to the IP address it checked, so DNS changes during a run can't send it somewhere else.

A URL that breaks these rules ends the run with status error, and the step explains why.

Secrets¶

Client secrets, bearer tokens and API keys are stored encrypted and are never shown again after you save them.

The test page and edit form show only Set / Not set.
To keep a stored secret when editing, leave the secret field blank. Enter a new value to replace it.
The API reports only whether a secret is stored, for example client_secret_set: true, and never returns the value.
In the Test Log, secrets and issued tokens appear as fingerprints, e.g. [redacted 64 chars sha256:9c1e…]. The same value always produces the same fingerprint, so you can tell whether two runs used the same secret without seeing it.
Audit entries record which secret was changed, never its value.

Editing and deleting¶

Edit changes the test's configuration. Later runs use the new settings, and earlier runs keep the snapshot they were run with.
Delete removes the test and its secrets and signing keys. Its Test Log entries are kept, showing the test's name and type at the time of the run.