Testing Overview

This page helps NOOSChain developers choose the right test level for a change. Use it as the entry point for local regression tests, verification commands, E2E tests, hardness tests, soak tests, chaos/stress tests, and performance benchmarks.

The guiding rule is:

Test evidence should match the risk and blast radius of the change.

A one-line UI or docs change does not need the same evidence as a protocol, state-root, consensus, or snapshot change. A release candidate does.

Which Test Should I Run?

Change	Start with	Add when risk is higher
Transaction handler, nonce, permission, or protocol behavior	Focused test:*, npm run verify:protocol, npm run verify:replay	npm run test-e2e:all
Sync, gossip, encryption, payload availability	npm run test:sync, npm run test:gossip, payload/encryption tests	npm run test-e2e:simple
Raft adapter, leader/follower behavior, membership	npm run test:raft, npm run test:raft:http, npm run test:raft:membership	Multi-producer hardness and soak
HashiCorp Go Raft sidecar	npm run test:raft:go, npm run test:raft:go:tcp-tls	HashiCorp hardness, chaos, and soak
State-root engine, Nervos sidecar, proofs	npm run test:state-root-v1	Hardness/soak with state-root activation enabled
Snapshots, import, restore, checkpoint replay	npm run test:snapshots	npm run test:snapshots:large, backup DR, Raft snapshot
Smart-contract runtime or package governance	Contract runtime/security/provenance tests	npm run contracts:rc-gate, npm run contracts:incident-drills, contract soak
Performance-sensitive changes	Targeted benchmark	Soak/stability when long-running behavior matters
Release candidate	Release-readiness matrix	Soak, hardness, docs, and operator-gate evidence

Common Command Matrix

Fast local regression and CI:

npm run test:ci
npm run test-e2e:simple
npm run test-e2e:all

Verification:

npm run verify:protocol
npm run verify:chain
npm run verify:replay
npm run verify:genesis

Raft and consensus:

npm run test:raft
npm run test:raft:http
npm run test:raft:go
npm run test:raft:go:tcp-tls
npm run test:raft:membership
npm run test:raft:snapshot

State root and snapshots:

npm run test:state-root-v1
npm run test:snapshots
npm run test:snapshots:large
npm run test:contract-backup-disaster-recovery

Hardness and soak:

npm run test-e2e:hardness-multiple-producers-noosraft
npm run test-e2e:hardness-multiple-producers-hashicorp-go
npm run soak:single-producer
npm run soak:multiple-producers-noosraft
npm run soak:multiple-producers-hashicorp-go

Smart contracts:

npm run test:contract-runtime-security
npm run test:contract-runtime-compatibility
npm run test:contract-mainnet-launch-gate
npm run test:contract-release-candidate-gate
npm run contracts:rc-gate
npm run contracts:incident-drills
npm run soak:contracts:smoke

Performance:

npm run benchmark:v1-readiness
npm run benchmark:v1-readiness:check
npm run benchmark:snapshots
npm run benchmark:state-root-engine
npm run benchmark:sync-catchup

Test Families

Fast focused tests protect individual modules and recent regression paths. Prefer these while iterating because they fail close to the code you changed.

Verification commands prove chain invariants from persisted state. Use them when protocol, replay, state roots, sync, snapshots, or migrations are touched.

E2E tests boot real app instances and exercise system behavior through HTTP APIs. Use them when the change crosses module boundaries.

Hardness tests combine multi-node behavior, failure boundaries, state-root activation, and operator observability. Use them for consensus, sync, and state-root release confidence.

Soak and stability tests run longer workloads. Use them for resource pressure, restart behavior, backfill, sidecars, and cluster liveness.

Benchmarks measure performance. They do not prove correctness.

Two-Node E2E

npm run test-e2e:simple starts a full local two-node NOOSChain integration environment. It is broader than individual test:* scripts because it boots two real Fastify application instances, gives each node an isolated PostgreSQL schema, and exercises the system through HTTP APIs.

The test environment is for local development only. It refuses to run with NODE_ENV=production, binds only to localhost, and only drops schemas whose names match the generated noos_e2e_node_a_* and noos_e2e_node_b_* test patterns.

What It Starts

• Node A on a random localhost port with NODE_ID=node-validator-a.
• Node B on a random localhost port with NODE_ID=node-validator-b.
• An isolated PostgreSQL schema for each node.
• A real Fastify server for each node.
• Single-node consensus adapters.
• HTTP sync and gossip paths between the nodes.

Each schema runs the normal migration stack. The test environment does not copy domain tables, SMT tables, or materialized state between nodes. Node B learns state by fetching blocks from Node A and executing them through the same deterministic block execution pipeline used by normal nodes.

How To Run

npm run test-e2e:simple

Structured JSON summary:

npm run test-e2e:simple -- --json

Readable logs plus archived summary:

npm run test-e2e:simple -- --report-dir ./test-results/noos

Keep generated schemas for debugging:

$env:NOOSCHAIN_E2E_KEEP_DB="true"
npm run test-e2e:simple

Coverage

The scenario verifies:

• genesis initialization and genesis sync;
• chain head convergence, chain verification, and replay on both nodes;
• HTTP transaction gossip and duplicate gossip handling;
• permissions, access-rule updates, bucket policy mutation, and deterministic unauthorized failures;
• encrypted record writes, key envelopes, bucket keys, record keys, and key rotation;
• local ciphertext availability differences that must not affect block hash or state root;
• payload backfill and batch payload retrieval;
• snapshot export, verification, import into a fresh schema, checkpoint replay, and post-snapshot sync;
• authentication, nonce, duplicate transaction, skipped nonce, stale nonce, and invalid signature rejection;
• observer read-only behavior;
• peer scoring visibility;
• final block-hash and state-root convergence.

Not Covered

The simple E2E harness does not cover:

• Raft consensus;
• HashiCorp Go Raft sidecar behavior;
• CometBFT or ABCI integration;
• libp2p transport;
• fork choice or automatic reorg;
• validator slashing;
• production-grade peer discovery;
• production authentication hardening beyond current session-token and node-auth primitives.

Use hardness, Raft, soak, and operator-gate tests for those layers.

Multi-Validator Hardness

Use hardness tests when a change affects consensus, sync, state-root activation, operator observability, conflict boundaries, or multi-producer behavior.

Key pages:

• Multi-Validator Hardness E2E
• E2E Hardness Testing

Commands:

npm run test-e2e:hardness-multiple-producers-noosraft
npm run test-e2e:hardness-multiple-producers-hashicorp-go

These tests are especially important for activation-boundary and fail-closed behavior across Noosraft and HashiCorp Go paths.

Raft And Consensus Tests

Use focused Raft tests while changing consensus internals:

Command	Purpose
npm run test:raft	In-process Raft behavior, persistence, restart safety.
npm run test:raft:http	HTTP transport, node-auth, real Fastify nodes.
npm run test:raft:go	HashiCorp Go sidecar bridge.
npm run test:raft:go:tcp-tls	HashiCorp Raft TCP TLS/mTLS behavior.
npm run test:raft:membership	Runtime membership reconciliation and safe operations.
npm run test:raft:snapshot	Raft InstallSnapshot catch-up and tamper rejection.

Related pages:

• Raft Chaos Testing
• HashiCorp Raft Chaos Testing
• NoosRaft Multi-Producer Soak
• HashiCorp Go Multi-Producer Soak

State-Root And Snapshot Tests

Use state-root tests when changing engine identifiers, root vectors, sidecar protocols, activation boundaries, proofs, or readiness.

npm run test:state-root-v1

Use snapshot tests when changing exported tables, canonical hashing, import, checkpoint replay, restore, or Raft snapshot catch-up.

npm run test:snapshots
npm run test:snapshots:large
npm run test:raft:snapshot
npm run verify:replay
npm run verify:chain

Related pages:

• State-Root Engine Migration
• Snapshot Internals
• SMT Candidate Evaluation

Smart-Contract Tests

Use smart-contract tests when changing manifests, ABI, host APIs, runtime limits, Wasmtime sidecar behavior, package provenance, registry policy, contract release workflow, migrations, or backup/restore behavior.

Good starting commands:

npm run test:contract-runtime-security
npm run test:contract-runtime-compatibility
npm run test:contract-runtime-preflight
npm run test:contract-mainnet-launch-gate
npm run test:contract-release-candidate-gate
npm run test:contract-backup-disaster-recovery

Release-level commands:

npm run contracts:rc-gate
npm run contracts:incident-drills
npm run contracts:sidecar:provenance
npm run soak:contracts:smoke

Related page:

• Contract Fuzz And Soak

Soak, Stability, And Stress

Use soak and stability tests when the risk is about time, load, restart, resource pressure, sidecar lifecycle, or cluster convergence.

Related pages:

• Single Producer Soak
• NoosRaft Multi-Producer Soak
• HashiCorp Go Multi-Producer Soak
• Stability Testing
• Failure Stress Testing
• Size Stress Testing

Common commands:

npm run soak:single-producer
npm run soak:multiple-producers-noosraft
npm run soak:multiple-producers-hashicorp-go
npm run stability:noosraft-chaos
npm run stability:go-raft-chaos
npm run stability:failure-stress
npm run stability:size

Performance Benchmarks

Benchmarks explain where time and resources go. They are not correctness tests.

Use Performance Benchmarks for the full benchmark catalog and report interpretation.

Common commands:

npm run benchmark:v1-readiness
npm run benchmark:v1-readiness:check
npm run benchmark:block-execution
npm run benchmark:state-root-engine
npm run benchmark:snapshots
npm run benchmark:payload-backfill
npm run benchmark:sync-catchup

Safety Rules

Local test harnesses must protect real data:

• refuse NODE_ENV=production;
• bind to localhost unless explicitly designed otherwise;
• use generated schema names;
• drop only generated schemas with known test prefixes;
• avoid production DATABASE_URL values;
• keep destructive cleanup guarded;
• redact secrets from logs and reports.

If a harness needs broader network binding, persistent databases, or real credentials, document the safety model before using it.

Reports And Debugging

Use --json when another tool needs machine-readable output.

Use --report-dir when evidence should be preserved for release readiness or a review thread.

Use NOOSCHAIN_E2E_KEEP_DB=true only when debugging locally. Clean up generated schemas after the investigation.

For release candidates, preserve:

• command output or JSON reports;
• relevant logs;
• generated summary files;
• benchmark reports;
• soak/stability reports;
• exact commit and environment metadata.

Review Guidance

For a small isolated change, run the focused test nearest the code and any affected verification command.

For protocol, replay, or state-root changes, run focused tests plus verify:protocol, verify:replay, verify:chain, and an E2E or hardness test.

For consensus changes, run the affected Raft tests plus a multi-producer hardness test.

For snapshot or restore changes, run snapshot tests, replay/chain verification, and any affected smart-contract backup/restore tests.

For a release candidate, use the broader matrix in Release Readiness.

Related Pages

• Release Readiness
• Multi-Validator Hardness E2E
• E2E Hardness Testing
• Stability Testing
• Performance Benchmarks
• SMT Candidate Evaluation
• Raft Chaos Testing
• HashiCorp Raft Chaos Testing
• Failure Stress Testing
• Size Stress Testing
• Contract Fuzz And Soak