External services

Tests are hermetic. Nothing assumes the network can reach a third party. When the program calls an external service, a flow that cannot be driven without it is Blocked and names what it needs. It never passes on a guess.

How services are found

Flow setup’s Detecting dependencies step finds the external services the program uses: the SDKs it imports, and the URLs in its source. Hosts listed in the recipe’s ownHosts do not count. Each service carries the environment variables the program reads its base URL from. Then Cataloguing dependencies declares every detected service in the recipe, including the ones you have no account for. The declaration enters the recipe’s fingerprint. The values you register never do, so rotating a key rewrites no tests.

The Dependencies tab

A repository’s Dependencies tab lists what the program needs you to provide. The columns are Dependency, Type, State and Used by.

Type	What it is
API service	A third-party API the program calls. You register an account for it.
Binary	An executable the program runs, which the machine must already have.
Login	A logged-in configuration directory.
Project	A real checkout the program operates on.
Credentials	The variables the program reads a secret from.

State	Meaning
Provided	An instance is registered, and the flows that need it run against it.
Incomplete	Part of the registration is missing, so a run stops rather than test against half of it.
Unprovided	Nothing is registered, and the flows that need it stay blocked.

Open a dependency to see what it must provide, when it applies and what it blocks. Registering it holds the form, with Save. A dependency that a test creates itself, or that the run prepares, has nothing to register and says so.

What you can register

In the web app you can register:

the variables of a Credentials dependency;
an API service’s base URL and the variables its declaration names.

The web app refuses two kinds of change:

a path or a directory, for a Project or a Login, because the server has no machine of yours to point at;
a new variable, a different base URL variable, or a different account mode, because each of those is a recipe edit and the web app does not edit the recipe.

Registered values are stored encrypted for the repository, under TRUECOURSE_SECRET_KEY, and every run receives them. A service whose values are all present is provided: the run injects them into the server’s environment, and Flow generation writes flows against the live service. A run that finds a service incomplete stops as missing-external-env.

Stubs

A test can stand up a stub for a third party: a local HTTP server that answers with exactly the responses the flow needs. The test points the program’s base URL variable at the stub with ${HTTP_STUB:<name>}:

setup:
  env:
    FORECAST_BASE_URL: ${HTTP_STUB:forecast}
  http:
    forecast:
      routes:
        - method: GET
          path: /v1/forecast
          status: 200
          json: { current: { weather_code: 4 } }
          calls: 1

calls pins how many times the program must call the route, and calls: 0 asserts it never does.

Faults on a real account

The program never reaches a provided service directly. Its traffic goes through a proxy the run controls, which forwards everything unless a test scripts a fault:

setup:
  externals:
    open-meteo:
      faults:
        - match: { method: GET, path: /v1/forecast }
          respond: { status: 503, json: { error: "upstream" } }
          once: true
      calls: 1

Rule	What it does
`respond`	Answers the call from the test instead of the service.
`delayMs`	Waits first, then responds or forwards.
`refuse`	Drops the connection without an answer.
`once`	Uses the rule once, then steps aside.

match picks which calls a rule applies to. calls asserts how many calls reached the service. Resolved values are masked in every transcript as «external:<service>.<VAR>».

Getting Started

Workspace

Context

Code

Flows

Settings

Configuration

Enterprise

How services are found

The Dependencies tab

What you can register

Stubs

Faults on a real account

Next steps

Flow generation

Flow run

​How services are found

​The Dependencies tab

​What you can register

​Stubs

​Faults on a real account

​Next steps

Flow generation

Flow run

How services are found

The Dependencies tab

What you can register

Stubs

Faults on a real account

Next steps