sedum.config.yaml in the current directory or
one of its parents. The folder containing that file is the project root. If no
file exists, the current directory is the root and the defaults below apply.
Paths and test globs are always relative to that root.
sedum run discovers regular
*.test.ts and *.test.yaml files under tests.directory, applies the
include/exclude globs, and runs the sorted result. Each test() in a
*.test.ts file is one test. Symlinked directories are not followed. An
explicit sedum run path/to/file.test.ts remains supported.
Settings resolve from defaults, then the top-level config, then the selected
named environment, then explicit command overrides. Named environments may
override baseUrl, browser, variables, provider.apiKeyEnv, and stepTimeoutMs. Nested settings
merge by field, so an override of viewport width retains the configured height.
For sedum run, --env selects the named environment before --browser and
--output-dir override their configured values. --url-override then replaces
the origin of the resolved entry URL, preserving its path, query, and fragment.
The browser resolves from, highest first: --browser (on run and doctor),
the SEDUM_BROWSER environment variable (from the process, then .env), the
selected environment’s browser, the top-level browser, then chrome. Set
SEDUM_BROWSER=chromium on a machine without Google Chrome, such as a Linux CI
or cloud container, instead of changing the shared config. sedum doctor
names the source it used.
Run-only --include, --exclude, --labels, and --name filters narrow the
discovered candidate files after config selection; explicit file and directory
arguments supply their own candidate set instead of applying the configured
test globs.
Sedum reads at most one dotenv file: <project-root>/.env. It never searches a
test directory, child, parent project, or sibling project for secrets. Values
from the invoking process override .env; both override config variables with
the same name. Provider credentials are accepted only from the process or this
.env, never from sedum.config.yaml. .env is ignored by Git and should not
be committed.
Custom credential variable names
Useprovider.apiKeyEnv to name the environment variable holding the selected
provider’s key or token. The vision fallback uses the same provider and key:
sedum run --env staging and sedum doctor --env staging use the named
environment’s values; environments without overrides inherit the top-level
names. sedum explore has no --env and uses the name sedum run uses without one. Set only variable names in YAML, never key values. Names must match
[A-Za-z_][A-Za-z0-9_]*. The process value wins over the project-root .env
value; blank values are treated as missing. An explicit name disables fallback
to the default names and aliases. Custom credential variables are not exposed
to tests and cannot be stored in config variables.
Sedum uses Node’s native .env parser. Parsing edge cases can vary by Node
version: Node 20, 22, and 24 do not retain __proto__ from .env, though an
explicit process environment value works. Prefer conventional uppercase names
such as TYPESAFE_LOCAL_E2E_API_KEY for portability.
Without these settings, existing behavior is unchanged: TypeSafe reads
TYPESAFE_API_KEY; OpenRouter reads OPENROUTER_API_KEY
or OPEN_ROUTER_API_KEY; Clef reads CLOUDFLARE_AUTH_TOKEN or
CLOUDFLARE_API_TOKEN. For Clef, provider.apiKeyEnv renames the token source;
CLOUDFLARE_ACCOUNT_ID is still required. Doctor, run diagnostics, and newly
generated init templates use the configured names. Existing init files are kept.
By default, Sedum sends jev-latest requests to TypeSafe. A gateway or other
TypeSafe System One-compatible service can be selected with these connection
variables:
/v1/systemone; the service must accept
that request and return the TypeSafe System One response shape. The URL defaults
to TypeSafe and the model to jev-latest; the API key is read from
TYPESAFE_API_KEY.
Process values override the project .env. TYPESAFE_API_KEY is rejected
from sedum.config.yaml.
For Vercel AI Gateway, keep provider.name: typesafe and use:
provider.model overrides the environment model. Use the gateway’s
model ID, not the direct jev-latest alias. The key must belong to the gateway;
Sedum does not automatically read AI_GATEWAY_API_KEY. See
gateway setup and supported decision models
for SDK usage, billing, and compatibility requirements.
OpenRouter decision models
To route Jev or another compatible System One model through OpenRouter:OPENROUTER_API_KEY in your shell or project-root .env. The existing
OPEN_ROUTER_API_KEY spelling is also accepted. Process values override .env
across both names; within one source, OPENROUTER_API_KEY wins. Neither name
may appear in config variables, and neither is forwarded to test variables.
Sedum uses OpenRouter’s TypeSafe-compatible System One endpoint
at https://openrouter.ai/api/v1/systemone, not chat completions. Fully qualified
model IDs are passed unchanged. Other decision models must support Sedum’s
Choice and Noul questions and response distributions; appearing in the
decision rankings is not a guarantee
of equivalent accuracy or limits. Direct Cloudflare Clef remains a separate provider.
This selection ignores TYPESAFE_* settings, including credentials. It applies
to runs, online validation, and affected-test selection. Cached
classifications are separated by provider and requested model. sedum doctor
sends a small, potentially billable request to the selected model.
Receipts identify openrouter and retain the returned model, token usage, and
usage.cost. Missing cost is unknown, not zero; direct Jev rates are never
applied to gateway calls. After any gateway retry, total cost remains unknown.
Other gateways can use the TYPESAFE_BASE_URL configuration above if they
implement the same System One protocol; a chat-only gateway is insufficient.
Direct Cloudflare Clef
To use Cloudflare Workers AI Clef for text decisions, configure one of the two supported models:CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_AUTH_TOKEN in the invoking
environment or project-root .env. Cloudflare’s conventional
CLOUDFLARE_API_TOKEN is accepted as an alias. Process values take precedence
over .env across both names; differing values for both names at the winning
level are rejected as ambiguous. Sedum builds the fixed Cloudflare account and
model route; Clef does not support a custom endpoint. Selecting Clef does not
change the default for other projects. See Clef
provider for scope, privacy, costs, and testing.
An absolute test url is unchanged. A relative test URL resolves against
baseUrl with standard URL semantics, and a missing test URL uses baseUrl
itself. A test with neither fails before the browser starts. Invalid config
errors name the file, source position, dotted key, and a concrete fix and exit
with code 3.
The thresholds settings control assertion verdicts. Locator and step
classification safety gates are deliberately not configurable. An explicit
JSON reporter writes to reporterDir/<run-id>/result.json; canonical progress
and result artifacts are always written under outputDir/<run-id>/.
Step timeout
stepTimeoutMs is how long one step waits for the page before it fails. It
defaults to 5000 (5 seconds) and accepts whole milliseconds from 0 to 120000.
It covers every step that depends on the page settling:
- Before a step is located or judged, a page that keeps re-rendering, such as
one that just changed route, gets at least 4 seconds to hold still, or
stepTimeoutMswhen that is longer. A page that never holds still fails the step withobservation_timeout, so--retriesreruns the test. - A
verifystep is judged again each time the page changes until its claim holds. A quoted-text check keeps reading a page that is mid-navigation. - A
clickortypestep whose target is not on the page yet is located again each time the page changes. - A located target that is not ready yet, such as a disabled or covered button
or a read-only field, is retried for at least 8 seconds, or for
stepTimeoutMswhen that is longer.
0 judges and locates each step once. An explicit wait up to 90 seconds until … step uses its own limit instead. The SEDUM_VERIFY_GRACE_MS
environment variable overrides the configured value for one run.
Experimental affected selection
affected.ignore is an optional string array, empty by default. With
sedum run --affected, it combines additively with each repeatable
--affected-ignore <glob>; command-line entries do not replace config entries.
Unlike test discovery globs, these patterns are relative to the Git repository
root, even when the Sedum project is a subdirectory. Use POSIX / separators.
Dotfiles are included, ** crosses directories, and a trailing / matches all
descendants. *.lock matches root lockfiles; **/*.lock also matches nested
ones. Empty or invalid patterns are rejected, as is --affected-ignore without
--affected. There are no automatic docs, config, or lockfile exclusions.
merge-base(base, pinned HEAD)..pinned HEAD, not local
edits. Use a clean CI checkout, explicitly fetch origin/main, and pass
--base origin/main; Sedum never fetches or merges automatically. The default
selection cutoff is --threshold 0.3, separate from assertion thresholds.
Chunk scores aggregate by maximum, not calibrated whole-PR probability.
The 16 MiB retained patch and 256 planned request guards fail closed, alongside
28,000-byte single-question and 56,000-byte batch limits (64 questions for Clef).
See Git-diff selection for lossless
chunking, costs, receipts, and the unverified accuracy caveat. Keep full-suite
CI; this experimental feature is not a mandatory gate.
Screenshots
screenshots (default true for the direct TypeSafe API, false for
gateways, compatible services and Clef) sends viewport screenshots to the
provider: an outlined screenshot that checks each model-resolved target for
ambiguity, and a screenshot with each verify and measure step. sedum run --screenshots and --no-screenshots override it for one run. Screenshots are
not redacted and are never sent for pages matched by --sensitive-origin. See
Screenshots for cost and behavior.
Vision fallback (opt-in)
Vision fallback is disabled by default. Enable it withvision.enabled: true
or sedum run --vision; --no-vision disables it for one run. It uses the
run’s TypeSafe provider and key: Jev’s image model (jev-1.14.0, the TypeSafe
images preview) reads a viewport screenshot in which every visible candidate
is boxed and labelled. It needs screenshots, so it is
available on the direct TypeSafe API, where screenshots are on by default. A
run with vision on and screenshots off (Clef, a gateway, screenshots: false
or --no-screenshots) stops before tests start with
vision_needs_screenshots. vision.model and vision.timeoutMs, which
configured the earlier OpenRouter resolver, are rejected with a fix; delete
them.
Enabling vision sends unredacted viewport screenshots to TypeSafe. Use
non-sensitive pages. Text redaction does not redact screenshot pixels, and no
screenshot is sent for pages matched by --sensitive-origin.
With vision enabled, ambiguous clicks use visual evidence instead of the
default permissive Jev repeated-member pick. Existing deterministic resolution
still runs first. With vision disabled, Jev’s behavior is unchanged. Core API
callers can explicitly override this via repeatedMember; an explicit
modelPick: true takes precedence over vision.
Only clicks can invoke vision: when Jev’s pick among repeated controls is
ambiguous, or when Jev finds no matching element at all, for example a target
described by its picture. In the second case vision chooses among every
visible control or abstains, and an abstention keeps the step’s none.
Missing controls, fills, assertions, and provider failures do not activate it.
Jev answers one Choice over the labels plus ambiguous and no_match, and
how many elements on screen fit the step. A label is used only at a
probability of at least 0.9, and only when Jev does not think that no element
(probability 0.3 or more) or several elements (0.5 or more) fit; otherwise
the step abstains. Unknown IDs and changed page versions are rejected;
execution still uses Sedum’s normal target and actionability checks, and the
target check still reviews the pick. Visual
layout changes without a DOM revision are not detected. Only fully visible,
unobscured controls are offered; fewer than two or more than 40 visible
controls leave the step unresolved.
There is at most one vision call per step, with no recovery after failure.
After vision is attempted, a stale action target fails without re-resolving.
Suppressing screenshots on sensitive pages does not restore permissive picks.
Existing Jev caching is unchanged; vision-selected targets are not cached.
HTML, Markdown, and CLI summaries identify vision fallback outcomes, the model,
trigger, and duration. A selected candidate is not a guarantee that its action
succeeded: the step verdict still reports execution separately. Text-model
confidence is not presented as vision confidence.
Usage summaries separate text and vision calls across all attempts, including
earlier retries. CLI usage is shown in interactive terminals or with --costs;
fallback details are also shown in non-interactive output. Vision calls are
priced at the Jev rate; see Screenshots.
Locator diagnostics include vision request duration and a safe failure
category (timeout, cancellation, connection, a rejected request, or an
invalid response). These fields are preserved in the canonical run result at
steps[].locator.vision; failures also appear in the step error message.
A rejected key or exhausted rate limit stops the run, as it does for every
other provider request.
The run summary says which vision model was enabled and on how many steps it
ran. A click that fails without vision being able to run says why, for
example because fewer than two controls were fully visible. sedum doctor
fails its vision check when vision is enabled but screenshots are off.