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 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
• 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
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

Scripts

Command	Description
npm test	Full action test suite (27 ACTION types, --timeout 0, requires live stack)
npm run test:unit	Unit tests (553 tests, no services required)
npm run test:integration	Integration tests (188 tests: 109 stubbed I/O + 79 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 (144 tests, edge cases and limits)
npm run test:fuzz	Fuzz tests (53 tests, property-based via fast-check)
npm run test:fuzz:quick	Quick fuzz (30s timeout)
npm run test:chaos	Chaos engineering tests (80 tests, failure injection)
npm run test:chaos:quick	P0 chaos only
npm run test:regression	Full regression suite (147 tests, P0+P1+P2)
npm run test:regression:p0	Regression P0: critical gate (101 tests, < 500ms)
npm run test:regression:p0p1	Regression P0+P1: merge gate (124 tests, < 500ms)
npm run test:perf	Performance tests with custom reporter
npm run test:perf:actions	Performance-instrumented action tests
npm run test:perf:e2e	Performance-instrumented E2E tests
npm run test:mutate	Mutation testing, Phase 1 (unit tests only)
npm run test:mutate:integration	Mutation testing, Phase 2 (unit + integration)
npm run perf:gate	CI performance gate check
npm run perf:report	Generate performance report
npm run mutate:report	Generate mutation testing report

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
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.