Variables & Secrets

The ctx.vars and ctx.secrets objects provide access to environment variables and secure secrets during test execution.

For env file naming, load order, and system fallback, see Environments & Secrets. This page focuses on SDK runtime access patterns.

The rule

Put normal runtime config in ctx.vars and sensitive values in ctx.secrets.

Required vs optional

Use require() when the test cannot continue without a value. Use get() when a sensible fallback exists.


export const healthCheck = test("health", async (ctx) => {
  const baseUrl = ctx.vars.require("BASE_URL");
  const region = ctx.vars.get("REGION") ?? "us-east-1";
});

Secrets

Secrets should always be accessed through ctx.secrets. Do not put API keys in ctx.vars.


export const testAuth = test("auth", async (ctx) => {
  const apiKey = ctx.secrets.require("API_KEY");
  const res = await ctx.http.get("...", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
});

Values read through ctx.secrets are automatically treated as sensitive by the runner and redaction pipeline. They never appear in traces, logs, or the Cloud dashboard.

Validation functions

You can pass a validator to require() when presence alone is not enough:


export const validateConfig = test("validate", async (ctx) => {
  const port = ctx.vars.require("PORT", (v) => !isNaN(Number(v)));
 
  const jwt = ctx.secrets.require("JWT_TOKEN", (v) => {
    const parts = v.split(".");
    if (parts.length !== 3) {
      return "must be a valid JWT containing 3 parts separated by dots";
    }
    return true;
  });
});

Validator return values:

true, undefined, or null — validation passed
false — validation failed (generic error)
string — validation failed with a custom error message

Using with configure()

When many tests share the same vars and secrets, declare them once with configure(). Values use {{KEY}} template syntax and resolve lazily:


import { configure, test } from "@glubean/sdk";
 
const { vars, secrets, http } = configure({
  vars: { baseUrl: "{{BASE_URL}}" },
  secrets: { apiKey: "{{API_KEY}}" },
  http: {
    prefixUrl: "{{BASE_URL}}",
    headers: { Authorization: "Bearer {{API_KEY}}" },
  },
});

See Configuration for full details.