Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
Writing tests
Read this before writing or reviewing a test.
A complete test
// main_test.go: once per package
func TestMain(m *testing.M) { harness.Main(m, harness.Shared) }
func TestSecret_Create(t *testing.T) {
t.Parallel()
h := harness.From(t)
t.Run("should refuse and keep the original when the same name is created twice", func(t *testing.T) {
t.Parallel()
// Setup
tn := h.NewTenant(t)
proj := fixture.NewProject(t, tn, fixture.WithProjectType("secret-manager"))
secretmanager.CreateSecret(t, proj, "dev", "TOKEN", "first")
// Action
res, err := tn.Admin.API.CreateSecretV4WithResponse(t.Context(), "TOKEN",
api.CreateSecretV4JSONRequestBody{
ProjectId: proj.ID,
Environment: "dev",
SecretPath: new("/"),
SecretValue: "second",
})
// Assert
require.NoError(t, err)
require.NotEqual(t, http.StatusOK, res.StatusCode())
require.Equal(t, "first", secretmanager.GetSecret(t, proj, "dev", "TOKEN").Value)
})
}
Profiles
| Profile | Gives | Use when |
|---|---|---|
harness.Shared |
one instance for the run, a fresh organization per test | almost always |
harness.Isolated |
the package's own Postgres, Redis, and Infisical | the test writes instance-wide state: super-admin config, login methods, encryption strategy, run modes |
Isolated costs a full boot per package, so an Isolated package lives under
suitesisolated/, where make test-isolated and CI run one package at a time after the
shared suites; a layout test in harness/ fails a misplaced one. Containers the test talks to through Infisical,
such as a rotation target database, are added with harness.WithInfra(...). Instance-wide
environment, such as RELAY_AUTH_SECRET, is set with harness.WithInfisicalEnv(k, v),
which only an Isolated package may use.
Structure
- Setup in about eight lines, the action as one call, one to three assertions. A longer setup is a missing helper.
- Where the action is the assertion (
ExpectEvent), write// Action + Assert. - Add a
requiremessage only when the values do not explain the failure. - Never call
requirefrom another goroutine; collect results and assert after.
Naming
- Function:
Test<Resource>_<Behaviour>. - Subtest:
should <outcome> [when <condition>], lowercase. The outcome first, so a list of failures reads as a list of broken claims. - A subtest name is a claim that can fail:
good should hold a separate value per environment when one name is created in two
bad should create secret in prod env a label; claims no outcome
good should refuse and keep the original when the same name is created twice
bad should handle duplicates "handle" cannot fail
- The subject is the operation being claimed about. Operations used for setup or observation are not subjects.
- One file per resource or flow; variants of a flow are subtests.
Outcomes
The unit is (operation, outcome), not line coverage.
- Assert what a caller depends on, not that a route responded.
- Cover failure outcomes: refused, forbidden, another tenant's resource, not found, conflicting, unlicensed, repeated.
- A rejection test also checks that nothing changed.
- Assert error bodies where the message is part of the contract
(
backend/CODE_QUALITY.md). - Use the actor the claim is about.
- When the name cannot carry the reason, add one line with
spec.Why. Most tests do not need it.
Waiting
- Never sleep.
- Infisical's own state, such as a sync status: poll the API with
internal/wait. - What a fake did: wait on its fake events with
ExpectEvent. See fakes.md. - Wait on the status the product records first, for a readable failure, then assert the outcome at the destination. A status alone does not prove the work happened.
- Interval-driven features: use the product's manual trigger instead of waiting for the interval.
- Deadline-driven features: move the deadline, not the clock.
- Budget: a single wait fits inside
wait.For's default 30 second timeout. Delays the product builds in count against it, such as a sync job's random 0-10 second start jitter plus the 3 second debounce before an auto-sync.
The harness API
h := harness.From(t)
tn := h.NewTenant(t) // organization; tn.Admin signed up and owns it
tn.Email("alice") // alice@<tenant-domain>.test
tn.NewUser(t, harness.WithName("alice")) // invited through mail
tn.NewMachineIdentity(t, harness.OrgRole("admin"))
tn.Client(t, token) // a client on this tenant's rate-limit bucket
h.InstanceAdmin(t) // super admin; Isolated only
proj := fixture.NewProject(t, tn, fixture.WithProjectType("secret-manager"))
proj.NewUser(t, fixture.WithPrincipalName("bob"), fixture.WithRoles("admin"))
proj.Grant(t, principal, "developer")
proj.NewRole(t, "reader", fixture.Permission{Subject: "secrets", Action: []string{"read"}})
secretmanager.CreateSecret(t, proj, "dev", "DB_URL", "value", secretmanager.As(member))
secretmanager.GetSecret(t, proj, "dev", "DB_URL")
- Fixtures take required arguments positionally and the rest as options.
harness.OrgRoleandfixture.WithRolesare separate types, so organization and project roles cannot be mixed up.
Entitlements and rate limits
Every tenant gets an enterprise plan, resolved per organization.
tn := h.NewTenant(t, harness.WithPlan(license.Enterprise().Without(license.RBAC)))
tn.SetPlan(t, license.Enterprise()) // verifies it took effect
- Pin downgrade behaviour with
should ... when the plan does not include it. A license check must never change a read path (backend/CODE_QUALITY.md). - Only plan-derived rate limits can be raised. The rest are per source address, which is why each tenant and principal gets its own and why clients are never built by hand.