@deployagram/environment
v1.0.0
Published
Finds or starts the Deployagram Collector and HTTP Proxy for Node.js tests: reuses a running one (by URL or Docker image), otherwise starts it with testcontainers.
Readme
@deployagram/environment
Finds, or starts, the Deployagram Collector and HTTP Proxy for Node.js tests. It is the Node.js
equivalent of the Java deployagram-environment module.
For each service it tries, in order:
- A URL, from the options or from
DEPLOYAGRAM_LOGGER_URL/DEPLOYAGRAM_PROXY_URL. If set, it must be reachable, or the call fails. It does not fall back to starting one. - A running container whose image starts with the expected name and publishes port 8080. Found with the Docker API.
- A new container, started with testcontainers, if neither of the above exists.
Your normal setup, with the Collector started by hand, is covered by step 1 or 2. Nothing has to be started for the tests.
npm install @deployagram/environmentimport { startDeployagramEnvironment, stopDeployagramEnvironment } from '@deployagram/environment';
const env = await startDeployagramEnvironment();
env.logger.url; // e.g. http://localhost:1152
env.proxy?.url; // e.g. http://localhost:9080, or undefined with proxy: false
// later, when the run is over
await stopDeployagramEnvironment();startDeployagramEnvironment runs once per process and returns the same environment after that.
In Vitest, call it from a globalSetup file and call stopDeployagramEnvironment in its teardown.
Options
| Option | Default | Meaning |
|---|---|---|
| loggerUrl | DEPLOYAGRAM_LOGGER_URL | Collector URL to use. Must be reachable. |
| proxyUrl | DEPLOYAGRAM_PROXY_URL | Proxy URL to use. Must be reachable. |
| proxy | true | false starts and finds no Proxy, for a Collector-only test with in-process stubs such as MSW or Nock |
| loggerImage | the owner's collector image | Image name matched by prefix |
| proxyImage | the owner's proxy image | Image name matched by prefix |
| network | deployagram | Docker network for started containers. Created if missing. |
| loggerEnvironment | {} | Extra environment for a started Collector, such as KAFKA_BROKER_LOCATION_MODE=RUNTIME |
| proxyConfig | {} | Proxy configuration to start the Proxy with |
| env | process.env | Environment variables to read |
| cwd | current directory | Where to find the .deployagram licence file |
Licence and credentials
To start a container, the licence and key are required:
DEPLOYAGRAM_LICENSE, or the.deployagramfile in the working directoryDEPLOYAGRAM_LICENSE_KEY
Cloud credentials (DEPLOYAGRAM_CLIENT_ID, DEPLOYAGRAM_CLOUD_USERNAME,
DEPLOYAGRAM_CLOUD_PASSWORD) are passed to a started Collector. Reusing a running service needs
none of these.
Differences from the Java module
- The Java module starts the Proxy on a fixed host port when
proxyPortis set. Here the Proxy is given a random port, and tests read its URL from the environment, so no fixed port is needed. - A URL that is set but unreachable is an error. The Java module has no URL setting.
- A started Proxy reaches a started Collector through the Docker network alias
diagram-logger. A Collector found in Docker is reached by container id on the same network, as in Java. A Collector given by URL is reached throughhost.docker.internal.
Requirements
- Docker, to find or start containers. A URL-only setup needs no Docker.
- To start containers, the owner's collector and proxy images, pulled from the private registry.
Testing
npm testTests use fake dependencies and an HTTP stub (MSW). They need no Docker and start no containers. The Docker lookup and the testcontainers start are not covered by unit tests. They were checked by hand against the running Collector.
