Testing - Neo N3 MCP Server

Test commands

Command	Scope	External network
`npm run test:unit`	Deterministic Jest tests excluding `tests/mcp-*.test.ts`.	No
`npm run build`	Clean TypeScript compilation to `dist/`.	No
`npm run test:mcp`	Built-server smoke, stdio lifecycle, and modern tool-registration checks.	No
`npm run test:all`	Unit tests, clean build, then deterministic MCP tests.	No
`npm run verify`	Type check, deterministic unit tests, build, and deterministic MCP tests.	No
`npm run test:mcp:live`	Broader MCP and public RPC behavior.	Yes
`npm run test:integration`	Standalone built-server integration runner.	Yes
`npm run test:mcp:stress`	Explicit concurrency and load behavior.	Some cases
`npm run test:coverage`	Unit coverage report without a configured minimum threshold.	No

Default validation

npm ci
npm run verify
npm audit --audit-level=high
npm audit --omit=dev --audit-level=high
npm pack --dry-run

A deterministic failure is a failure to fix. The project does not classify failed unit tests as expected security validations.

Live and stress suites

Build first because these suites execute dist/index.js.

npm run build
npm run test:mcp:live

npm run test:integration

npm run test:mcp:stress

Public RPC availability, latency, and plugin support can affect live results. Investigate failures in that context rather than hiding them in the deterministic suite.

Focused Jest runs

npm run test:unit -- --runInBand tests/http-server.test.ts

npm exec -- jest --runInBand \
  tests/documentation-surface.test.ts \
  tests/production-assets.test.ts \
  tests/package-surface.test.ts

Tests follow the tests/*.test.ts convention. Shared MCP process helpers are in tests/mcp-test-utils.ts.

Docker validation

npm run docker:test

HTTP_API_KEY=local-ci-check-key-0000000000000000 \
  docker compose -f docker/docker-compose.yml config
docker compose -f docker/docker-compose.dev.yml config

The CI container job also builds both Dockerfiles and waits for the production image health check.

Manual HTTP checks

npm run build
export HTTP_API_KEY="$(openssl rand -hex 32)"
NEO_NETWORK=testnet npm run start:http

curl http://127.0.0.1:3000/live
curl http://127.0.0.1:3000/health

curl -H "Authorization: Bearer $HTTP_API_KEY" \
  http://127.0.0.1:3000/metrics

curl -H "Authorization: Bearer $HTTP_API_KEY" \
  http://127.0.0.1:3000/api/blockchain/height

Also verify that a missing bearer token returns 401, an oversized body returns 413, a non-JSON POST returns 415, and string or numeric confirmation values are rejected.

CI coverage

Node.js 22 and 24 run type checking and deterministic unit tests.
Node.js 22 generates coverage locally in the job; there is no Codecov upload.
The build job runs a clean build, deterministic MCP tests, and package validation.
The security job runs full and production-only audits.
The container job validates Compose and both images.
Live, integration, and stress suites are not in the default workflow.