XChain Platform End-to-End Test Suite

End-to-end Mocha test suite for the XChain Platform. Exercises the full platform stack (encoder, decoder, indexer, explorer, hub, UTXO tracker, and regtest miner) against a live regtest deployment. Tests are not mocked; they broadcast real transactions to a regtest coin node and verify that the platform processes them correctly end to end.

Features

• 27 ACTION test suites: ISSUE (V0-V5), SEND (V0-V3), MINT, DESTROY, ORDER, DISPENSER, SWAP, DIVIDEND, AIRDROP, FILE, MESSAGE, BROADCAST, ADDRESS, LINK, LIST, CALLBACK, BATCH, SWEEP, SLEEP, COINPAY, STAKE, DEPLOY, EXECUTE, DEPOSIT, WITHDRAW
• Full transaction lifecycle: BIP39/BIP32 wallet generation, regtest funding, PSBT construction, signing, broadcast, mining, indexer verification
• 7 service connectors: BlockchainConnector, XChainUtxoTrackerConnector, XChainEncoderConnector, XChainIndexerConnector, XChainHubConnector, RegtestMinerConnector, and MariaDB Database class
• Hub auto-discovery: falls back to xchain-hub for service endpoint resolution when env vars are not set
• Multi-chain support: Bitcoin, Litecoin, and Dogecoin today on regtest
• P2SH two-step encoding: automatic detection and handling of two-transaction P2SH flows for messages exceeding 76 bytes
• Database polling assertions: 30+ waitFor* methods that poll the indexer MariaDB until ACTION records appear, with configurable timeouts and performance tracking
• UTXO verification cache: tracks confirmed UTXOs between transactions to avoid stale mempool entries
• Wallet memory cleanup: seed and private key buffers are zeroed during teardown
• Performance instrumentation: bootstrap phase timing, per-poll metrics, custom Mocha reporter writing JSON to perf-results/
• Federation and attestation tests: multi-hub PBFT round-trip suites (multiHubAttestation, llmAttestation, nodeProof) exercising quorum, consensus state buffering, and LLM/http_get attestation providers
• SDK-driven tests: action lifecycle tests via the bundled xchain-sdk local package, including chunked DEPLOY, x402, MCP, and ticker-ID equivalence
• Security tests: VM sandbox escape, policy enforcement, and input validation suites against the live regtest stack
• Codec unit tests: standalone encoder/decoder wire-format tests with no services required
• Multi-chain parity tests: cross-chain ledger-hash and state consistency checks across Bitcoin, Litecoin, and Dogecoin today
• Mutation testing: Stryker Mutator with two-phase config (Phase 1: unit only; Phase 2: unit + integration)
• 1777+ tests: actions, unit, integration, e2e, federation, sdk, smoke, boundary, fuzz, chaos, regression, security, codec, parity, mutation, and performance

Documentation

Full documentation is available in the xchain-documentation repository:

Document	Description
README	Overview, architecture, test lifecycle, service connectors
Architecture	Data flow, connector classes, bootstrap sequence, polling pattern
Configuration	Environment variables, hub discovery fallback, Docker setup
Operations	Running tests, Docker execution, troubleshooting, CI integration

Quick Start

Clone the repository and install dependencies:

git clone https://github.com/XChain-Platform/xchain-e2e-test.git
cd xchain-e2e-test
npm install

Create a .env file (or let the suite discover config from xchain-hub):

COIN=bitcoin
NETWORK=regtest
NODE_URL=localhost
NODE_PORT=18443
NODE_USER=rpc
NODE_PASSWORD=rpc
UTXO_TRACKER_URL=localhost
UTXO_TRACKER_API_PORT=3030
ENCODER_URL=localhost
ENCODER_API_PORT=3031
# Optional. Only needed when the encoder is deployed with API_KEY set; the
# harness then sends it as x-api-key, which the encoder requires on every
# JSON-RPC method including ping. Leave unset for an unkeyed encoder.
ENCODER_API_KEY=
INDEXER_URL=localhost
INDEXER_API_PORT=3032
INDEXER_DB_NAME=XChain_BTC_Regtest_Indexer
INDEXER_DB_USER=indexer_user
INDEXER_DB_PASS=indexer_pass
REGTEST_MINER_URL=localhost
REGTEST_MINER_API_PORT=3033

Run the full action test suite (requires all services running):

npm test

Run tests that don't require live services:

npm run test:unit
npm run test:regression:p0

Running the SDK suites locally

test/sdk/** requires two packages that package.json declares as file:./xchain-sdk and file:./xchain-hub: local, gitignored vendor directories that a fresh checkout does not have. Without them, those suites fail at require() time with Cannot find module 'xchain-sdk'.

The CI venue fills ./xchain-sdk and ./xchain-hub with real staged package snapshots before it runs npm ci. Nothing in this repo does that automatically on npm test (no pretest hook), because a pretest would silently overwrite a CI-staged snapshot with a symlink the next time CI ran this script by mistake. Staging is therefore a separate, opt-in step you run by hand:

npm run stage:siblings:check   # report state, changes nothing
npm run stage:siblings         # symlink ../xchain-sdk and ../xchain-hub in, if empty
npm install                    # only if node_modules/xchain-sdk or xchain-hub were stale

npm run stage:siblings symlinks the sibling xchain-sdk and xchain-hub checkouts (../xchain-sdk, ../xchain-hub, next to this repo) into the vendor slots when they are absent or empty. If a directory already holds a staged snapshot (its own package.json), the script leaves it alone and says so; it never overwrites real content. Remove a symlink it created with node scripts/stage-siblings.js --unstage.

Scripts

Command	Description
npm test	Full action test suite (27 ACTION types, --timeout 0, requires live stack, 305 tests)
npm run test:unit	Unit tests (1,644 tests, no services required)
npm run test:integration	Integration tests (334 tests: 117 stubbed I/O + 142 live)
npm run test:e2e	E2E meta-tests (38 tests, validates suite against live services)
npm run test:smoke	Smoke tests (18 tests, quick bootstrap and connectivity checks)
npm run test:boundary	Boundary tests (145 tests, edge cases and limits)
npm run test:fuzz	Fuzz tests (170 tests, property-based via fast-check)
npm run test:fuzz:quick	Quick fuzz (30s timeout, 170 tests)
npm run test:chaos	Chaos engineering tests (80 tests, failure injection)
npm run test:chaos:quick	P0 chaos only (23 tests)
npm run test:regression	Full regression suite (178 tests, P0+P1+P2)
npm run test:regression:p0	Regression P0: critical gate (138 tests, < 500ms)
npm run test:regression:p0p1	Regression P0+P1: merge gate (158 tests, < 500ms)
npm run test:perf	Performance tests with custom reporter (18 tests)
npm run test:perf:actions	Performance-instrumented action tests (305 tests)
npm run test:perf:e2e	Performance-instrumented E2E tests (38 tests)
npm run test:mutate	Mutation testing, Phase 1 (unit tests only)
npm run test:mutate:integration	Mutation testing, Phase 2 (unit + stubbed integration; the Docker-backed live suites are excluded so the score is host-independent)
npm run perf:gate	CI performance gate check
npm run perf:report	Generate performance report
npm run mutate:report	Generate mutation testing report
npm run stage:siblings	Symlink the sibling xchain-sdk/xchain-hub checkouts into the gitignored vendor dirs, when empty (see "Running the SDK suites locally")
npm run stage:siblings:check	Report vendor-dir and node_modules link state, changes nothing

Test Suite

Type	Tests	Description
Unit	~553	Connector methods, cryptoHelper, transactionHelper, action helpers, initialCheck logic, perfCollector
Integration	~188	Bootstrap flow, pipeline wiring, database polling, error propagation, wallet/UTXO cache (stubbed + live)
E2E	~38	Full lifecycle validation against live services (bootstrap, transaction pipeline, polling, teardown)
Smoke	~18	Bootstrap env vars, connector pings, database connectivity, crypto wallet, mining, gas token
Boundary	~144	WHERE clause construction, connector URL building, polling timeouts, connection pool exhaustion, global state
Fuzz	~53	Action message mutation, config parsing, connector inputs, crypto inputs, DB filters, type confusion
Chaos	~80	Bad PSBT, connector timeouts, DB disconnect, gas bootstrap failure, teardown failure, UTXO/wallet races
Regression	~147	Tagged cross-suite subset: P0 (101), P1 (23), P2 (20)
Security	~13	VM sandbox escape, policy enforcement, input validation against the live regtest stack
Federation	~16	Multi-hub PBFT round-trip: quorum, consensus state buffering, LLM/http_get attestation providers
SDK	~279	Action lifecycle via the bundled xchain-sdk package: chunked DEPLOY, x402, MCP, ticker-ID equivalence
Codec	~19	Standalone encoder/decoder wire-format tests, no services required
Parity	~3	Cross-chain ledger-hash and state consistency across Bitcoin, Litecoin, and Dogecoin today
Mutation	2 phases	Stryker Mutator: Phase 1 (unit), Phase 2 (unit + integration)
Performance	3 modes	Custom Mocha reporter, bootstrap timing, poll instrumentation
Actions	~226	Full action tests against live regtest (ISSUE, SEND, MINT, etc.)
Total	~1777+

Dependencies

Runtime

Package	Purpose
axios	HTTP client for all service connector JSON-RPC calls
bitcoinjs-lib	Bitcoin primitives: PSBT construction, transaction signing, address generation
bip32	BIP32 HD wallet key derivation
bip39	BIP39 mnemonic seed generation
ecpair	ECDSA key pair creation for PSBT signing
tiny-secp256k1	Elliptic curve math backend for BIP32 and ECPair
mariadb	MariaDB client for indexer database polling
mocha	Test framework (--timeout 0 for on-chain confirmation polling)
dotenv	Environment variable loading from .env files

Development

Package	Purpose
sinon	Mocking, stubbing, and spying for unit and integration tests
fast-check	Property-based (fuzz) testing with automatic shrinking
@stryker-mutator/core	Mutation testing framework
@stryker-mutator/mocha-runner	Mocha integration for Stryker

Related

• Regtest Development Guide: setting up a local regtest environment
• Regtest Miner: auto-mining service the E2E suite depends on
• Encoder: constructs XChain transactions tested by this suite
• Indexer: processes transactions and maintains token state verified by this suite
• Testing Guide: platform-wide testing philosophy and coverage

---

Copyright © 2025-2026 Dankest, LLC

Based on XChain Platform by Dankest, LLC – https://dankest.llc

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.

You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.