Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The testing strategy for Kodus Runtime is multi-faceted, combining Rust unit/integration tests for the core logic, example-based demonstrations for complex features, and usage scripts for the Node.js bindings. This ensures both the low-level Rust components and the high-level JavaScript/TypeScript interfaces are reliable and function as expected. The primary tools used are cargo test for the Rust crates and Node.js scripts for the addon and API examples.
Sources: README.md:195, apps/runtime/crates/core/tests/workflow.rs
Core Rust Crate Testing (kodus-core)
Testing for the kodus-core crate is handled through automated tests written in Rust. These tests focus on validating the correctness of individual components and their interactions in an isolated environment.
Test Environment Setup
To ensure test isolation and prevent interference, each test function that requires a persistent store creates a temporary directory. The tempfile::tempdir() function is used to create a unique directory for each test run, which is automatically cleaned up afterward. This allows the DurableStore to be initialized with a clean state for every test case.
Sources: apps/runtime/crates/core/tests/workflow.rs:8-9
This diagram illustrates the setup process for a typical test involving the DurableStore.
Workflow Engine Testing
The WorkflowEngine is a critical component, and its testing is comprehensive, covering various scenarios from simple happy paths to complex conditional logic and error handling.
Test Scenarios
The tests for the WorkflowEngine cover the following key areas:
| Scenario | Description | Source File |
|---|---|---|
| Happy Path | A simple workflow with a transform step is executed successfully. | apps/runtime/crates/core/tests/workflow.rs:7-20 |
| Complex Chains | A workflow with multiple, chained steps (Route, ExternalCall, Delay) is tested to ensure correct execution order and side effects. | apps/runtime/crates/core/tests/workflow.rs:23-71 |
| Filtering Logic | A test verifies that a Filter step correctly blocks an event that does not meet the required criteria (e.g., missing a specific tag). | apps/runtime/crates/core/tests/workflow.rs:74-87 |
| Conditional Logic | A test confirms that a Condition step (e.g., has_user_id) correctly fails an event that does not satisfy the condition. | apps/runtime/crates/core/tests/workflow.rs:90-116 |
| Builder Chaining | Verifies that the WorkflowBuilder correctly chains steps together automatically. | apps/runtime/crates/core/tests/workflow.rs:119-137 |
| Retry and DLQ | A test ensures that a failing workflow correctly triggers the retry mechanism and, upon final failure, sends the event to the Dead Letter Queue (DLQ). | apps/runtime/crates/core/tests/workflow.rs:140-170 |
Example: Retry and DLQ Test Flow
The execute_with_retry_and_dlq test validates the error handling and resilience of the workflow execution. An event is processed by a workflow designed to fail, and the test asserts that it is retried and eventually sent to the DLQ.
The following sequence diagram shows the interactions during this test.
Retry and Dead Letter Queue (DLQ) Simulation
The retry_dlq.rs example serves as a detailed integration test for the retry and DLQ mechanisms outside of the workflow context. It simulates a processing loop that can fail, demonstrating how an event's retry count is incremented and how backoff delays are applied.
The logic flow for this simulation is as follows:
The simulation function simulate_processing uses event tags to determine its behavior, allowing for deterministic testing of different scenarios:
will_fail_always: The function will always return an error.should_succeed_after_retries: The function will fail a specific number of times before succeeding.succeeds_immediately: The function will always succeed on the first try.
Sources: apps/runtime/crates/core/examples/retry_dlq.rs:152-174
Node.js Addon and API Testing
Testing for the Node.js integration is performed through example usage scripts that interact with the compiled Rust addon.
Node.js Addon Usage Examples
The nodejs-usage.js and nodejs-usage.ts files act as integration tests for the ts-addon. They demonstrate and validate the core functionalities exposed to the JavaScript/TypeScript environment.
Key functionalities tested include:
- Initialization:
new KodusRuntime('./data') - Event Persistence:
runtime.persistEvent(...)andruntime.persistEventWithMetadata(...) - Event Retrieval:
runtime.findEventsBySource(...) - Statistics:
runtime.getStats() - Workflow Management:
runtime.createWorkflow(...)andruntime.executeWorkflow(...) - Retry Policy Creation:
createRetryPolicy(...)
This code snippet from nodejs-usage.js shows how a workflow is created and executed from Node.js.
// 6. Criar e executar workflow
console.log('\n🔄 Criando workflow...');
const workflowId = await runtime.createWorkflow(
'payment-processing',
'Process payment events with validation'
);
console.log(`✅ Workflow criado com ID: ${workflowId}`);
// 7. Executar workflow
console.log('🔄 Executando workflow...');
const inputEvent = { /* ... event data ... */ };
try {
const processedEvent = await runtime.executeWorkflow(workflowId, inputEvent);
console.log('✅ Workflow executado com sucesso!');
} catch (error) {
console.log(`❌ Erro no workflow: ${error.message}`);
}
Sources: apps/api/examples/nodejs-usage.js:47-71
API Server Example
The express-app.js file provides an example of a complete API server built using Express.js on top of the Kodus Runtime addon. This serves as an end-to-end test, demonstrating how the runtime can be integrated into a real-world web service.
The example server exposes the following endpoints, which directly map to the addon's functions:
| Method | Endpoint | Description |
|---|---|---|
POST | /events | Persists a new event with metadata. |
GET | /events/:source | Finds all events for a given source. |
GET | /stats | Retrieves statistics from the DurableStore. |
POST | /workflows | Creates a new workflow definition. |
POST | /workflows/:workflowId/execute | Executes a workflow with the provided event data. |
GET | /health | A simple health check endpoint. |
Sources: apps/api/examples/express-app.js:13-109
This diagram shows the architecture of the Express.js example application.
Sources: apps/api/examples/express-app.js
Tooling and Commands
The project's README.md file specifies the commands for running tests and benchmarks.
- Run all tests:
cargo test - Run specific tests:
cargo test test_persist_batch - Run benchmarks:
cargo bench
Sources: README.md:195-204