Design principles

E2Engine is designed around a structured model of distributed-system testing rather than a particular test runner, command-line interface, or infrastructure implementation.

The following principles guide its architecture and APIs.

Declarative testing

E2Engine tests describe desired behavior rather than an execution script.

An Environment describes the participating services:

kind: Environment
spec:
  services:
    - id: fraud
      kind: http
      mode: mocked
      address: 127.0.0.1:8081
      fixtures:
        # ...

A Test describes a request and its expectations:

kind: Test
spec:
  request:
    http:
      method: POST
      url: http://127.0.0.1:8080/payments
  expect:
    http:
      status: 201
    calls:
      - service_id: fraud
        http:
          method: POST
          path: /check

The specification does not describe how to start routers, configure mocks, capture traffic, compare responses, or clean up runtime resources.

Those mechanics belong to E2Engine.

This separation keeps test specifications focused on the behavior being tested.

Structured model

The main E2Engine concepts are represented as structured resources and execution records:

Environment
Test
TestSuite
TestExecution
TestSuiteExecution

The same models are used across validation, persistence, execution, and external interfaces.

Execution results are structured as well. Requests, responses, expectations, observed calls, deviations, and errors remain separate fields rather than being reduced to log output.

TestExecution
│
├── request
├── response
├── expect
├── calls
├── deviations
└── error

This makes E2Engine results suitable for both human inspection and programmatic processing.

Separation of model and interface

The E2Engine model does not depend on its user interface.

Interface
    │
    ▼
E2Engine Core
    │
    ▼
Structured models

The CLI is responsible for command handling and presentation, while the core operates on transport-independent resources, requests, and results.

As a result, presentation decisions such as tables, compact identifiers, or human-readable summaries do not become part of the domain model.

The same structured model can therefore be used by different interfaces and automation.

Modular infrastructure

E2Engine separates the testing model from the infrastructure used to execute it.

Components interact through focused contracts for responsibilities such as:

• resource persistence;
• scheduling execution work;
• running tests;
• providing runtime services;
• routing service traffic;
• executing protocol requests;
• evaluating protocol-specific behavior.

Conceptually:

                E2Engine Core
                      │
          ┌───────────┼───────────┐
          │           │           │
          ▼           ▼           ▼
     Repository   Scheduler     Runner
                                  │
                         ┌────────┴────────┐
                         │                 │
                         ▼                 ▼
                     Services           Routing

The core depends on these boundaries rather than requiring every capability to be implemented directly inside it.

This keeps infrastructure choices replaceable without changing the test model.

Explicit service boundaries

Distributed-system behavior is observed at the service boundaries described by an Environment.

System under test
       │
       ▼
Environment service boundary
       │
       ├── observe interaction
       │
       ▼
real or mocked service

Requests passing through these boundaries can be recorded and evaluated against the expectations declared by a Test.

This allows E2Engine to verify both:

request ──▶ system ──▶ response
                       │
                       └── response expectations

system ──▶ services ──▶ observed calls
                       │
                       └── interaction expectations

The resulting observations are stored as structured execution data rather than existing only as runtime logs.

Deterministic behavior where possible

E2Engine aims to make the same inputs produce predictable execution behavior.

Examples include:

• TestSuite selectors resolve to a deterministic order;
• duplicate TestSuite selections are removed by resource identity;
• expectations have explicit matching semantics;
• execution state follows defined lifecycle states;
• results preserve the exact expectations that were evaluated.

Determinism is particularly important for automated testing because orchestration behavior should not introduce unnecessary ambiguity into test results.

Where execution is inherently concurrent or dependent on an external distributed system, E2Engine keeps the resulting observations explicit rather than assuming an ordering that it cannot guarantee.

Observable execution

A test result should explain what happened, not only whether the test passed.

For that reason, E2Engine persists execution records and structured summaries.

A failed TestExecution can contain:

expected behavior
        │
        ▼
    deviation
        ▲
        │
observed behavior

The execution can preserve the request, response, expected interactions, observed calls, and deviations that led to its status.

This makes execution results useful for debugging, CI/CD reporting, and automated analysis.

Configuration outside the test model

E2Engine distinguishes between the system being tested and the configuration of E2Engine itself.

Environment / Test / TestSuite
              │
              └── describe the test

E2Engine configuration
              │
              └── controls how E2Engine operates

Operational settings such as repository configuration, execution limits, worker settings, timeouts, and other runtime options do not belong in Test resources.

Where supported, operational configuration can be provided through configuration files or environment variables.

This keeps test definitions portable across different E2Engine deployments.

Explicit lifecycle and errors

Execution state is represented explicitly:

scheduled
    │
    ▼
 running
    │
    ├──▶ passed
    ├──▶ failed
    └──▶ error

A failed expectation and an execution error are different outcomes.

failed means that execution completed but observed behavior did not satisfy one or more expectations.

error means that E2Engine could not execute or evaluate the test normally.

Keeping these outcomes distinct makes both human diagnosis and automated processing more reliable.

Designed for humans and automation

E2Engine resources are intended to be understandable when written and reviewed by developers, while remaining structured enough for tools to create, validate, execute, and inspect them.

The same principle applies to results:

                  Structured model
                    /          \
                   /            \
                  ▼              ▼
             Developer       Automation

Stable schemas, explicit resource relationships, structured errors, deterministic operations where possible, and machine-readable execution results make the model usable without relying on CLI text or log parsing.

The goal is not to maintain separate human and machine representations of a test, but to provide one explicit model that works for both.

See Architecture overview for the main E2Engine components and Extending E2Engine for the architectural extension points.