macalbert/envilder/core-testing

Envilder Testing Conventions

Outcome

Produce behavioral verification that matches Envilder standards and protects the risk identified by an approved VerificationContract.

When To Use

• Establishing, reusing, or updating tests for application or domain behavior
• Updating tests after refactors in CLI, GHA, infrastructure, or ports
• Reviewing whether test style is consistent before opening a PR
• Diagnosing test infrastructure after consumer evidence proved insufficient

Inputs

• Target behavior, file, or feature to test
• Test level: unit, integration, or e2e
• Any error paths or edge conditions to validate

Procedure

1. Read the approved intent, behavior, invariants, and verification strategy.

• Do not add a test when a compiler, schema, direct workflow, existing

baseline, or other oracle protects the requirement more directly.

1. Classify the justified test level.

• Use unit tests for pure domain or application behavior with stable ports.
• Use mocked port contracts (vi.fn()) for application handlers.
• Use integration or e2e tests when cloud, DI, CLI, GitHub Action, or

cross-layer wiring is the actual risk.

1. Create or update only the verification artifacts required by the contract.

• App and domain tests: tests/ mirrored to src/ structure.
• E2E tests: e2e/ using LocalStack/TestContainers.

1. Name tests using the required pattern.

• Should_<Expected>_When_<Condition>
• Example: Should_ThrowError_When_SSMParameterIsNotFound

1. Write tests with explicit AAA sections.

• Add comment markers in each test block:
• // Arrange
• // Act
• // Assert
• Each marker appears at most once per test. If you need to

test two actions or two assertions on different behaviors, write two separate tests.

1. Mock at the port boundary for application tests.

• Build test doubles by implementing domain port interfaces.
• Prefer vi.fn() to control behavior and assertions.

1. Validate primary success and failure paths required by the contract.

• Success path (expected output/state change)
• Domain error path (invalid input, missing parameter, etc.)
• Empty/no-op behavior where relevant

1. Keep assertions behavior-focused.

• Assert effects and interactions, not implementation details.
• Verify calls to injected ports and logger where behavior requires it.

1. For test-support changes, run a production-behavior consumer or direct

workflow first. Add a focused support test only for a documented diagnostic precision gap.

1. Run the targeted contract command and assigned broader gates.

• pnpm test
• pnpm lint
• For CI parity when needed: pnpm test:ci

Decision Points

• If a business rule is pure and deterministic: use a domain unit test.
• If orchestration calls multiple ports: test command handler with mocked

dependencies.

• If AWS integration semantics are the risk: add or update e2e with LocalStack.
• Require e2e only when behavior changes cannot be proven confidently with unit

tests.

• If only formatting/import changes occurred: update tests only when behavior

changed or snapshots/assertions became stale.

• If the intent is PURE_REFACTOR: establish a green baseline and keep

behavioral tests unchanged.

• If the intent is NON_BEHAVIORAL_CHANGE: do not manufacture a test.

Completion Criteria

• Test names follow Should_<Expected>_When_<Condition>
• AAA markers are present, clear, and appear at most once each per test
• Positive and negative paths are both covered
• No mandatory coverage percentage threshold is enforced by this skill
• Verification rejects the incorrect or previous behavior for the expected

reason when a negative signal is practical

• Tests run green locally with pnpm test
• No type/lint regressions from test changes (pnpm lint)

Quick Prompt Examples

• "Use testing-conventions for PullSecretsToEnvCommandHandler and add missing error-path tests."
• "Apply testing-conventions to review tests/envilder/apps/gha/entry/Gha.test.ts for naming and AAA compliance."
• "Use testing-conventions to design e2e coverage for SSM not-found behavior."

Anti-Pattern: Duplicate Act/Assert Blocks

Wrong: two Acts and Asserts in one test:

it('Should_HandleParameters_When_Called', async () => {
  // Arrange
  const mockData = { KEY: '/ssm/path' };
  // Act
  await handler.handle(commandA);
  // Assert
  expect(mockStore.saveEnvironment).toHaveBeenCalledOnce();
  // Act
  await handler.handle(commandB);
  // Assert
  expect(mockStore.saveEnvironment).toHaveBeenCalledTimes(2);
});

Correct: split into two focused tests:

it('Should_SaveEnvironment_When_CommandAProvided', async () => {
  // Arrange
  const mockData = { KEY: '/ssm/path' };
  // Act
  await handler.handle(commandA);
  // Assert
  expect(mockStore.saveEnvironment).toHaveBeenCalledOnce();
});
it('Should_SaveEnvironment_When_CommandBProvided', async () => {
  // Arrange
  const mockData = { KEY: '/ssm/path' };
  // Act
  await handler.handle(commandB);
  // Assert
  expect(mockStore.saveEnvironment).toHaveBeenCalledOnce();
});