> For the complete documentation index, see [llms.txt](https://quantumwing.gitbook.io/quantumwing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumwing.gitbook.io/quantumwing/development/testing.md).

# Testing

Running the test suite, coverage targets, and CI conventions

The full coverage breakdown lives in [../TESTING.md](https://github.com/dolfrin/QuantumWing/blob/master/docs/TESTING.md); this page is the operational quick-reference for contributors.

## Run everything

```bash
./scripts/test-all.sh
```

This wrapper runs `go vet`, the full Go test suite, and the explorer TypeScript typecheck. It is what CI runs and what every PR must pass.

For just the Go side:

```bash
go test -count=1 -timeout=5m ./...
```

`-count=1` disables Go's test cache so retries run for real (cache hits hide flaky tests).

## With coverage

```bash
go test -count=1 -timeout=5m -coverprofile=/tmp/cover.out ./...
go tool cover -func=/tmp/cover.out | tail -1
go tool cover -html=/tmp/cover.out -o /tmp/coverage.html
open /tmp/coverage.html
```

Aggregate coverage at present: \~19.5% (see [../TESTING.md](https://github.com/dolfrin/QuantumWing/blob/master/docs/TESTING.md) for the per-package matrix).

## Targeted runs

```bash
# Cryptography
go test -v ./crypto/dilithium
go test -v ./vrf

# Consensus engine
go test -v ./blockchain/consensus/por
go test -v ./blockchain/consensus/por -run 'Test(Slashing|Reward|StateManager)'

# State + storage
go test -v ./blockchain/storage
go test -v ./blockchain/state

# Networking
go test -v ./blockchain/p2p
go test -v ./blockchain/p2p/dnsdisc

# Smart contracts
go test -v ./qwvm
go test -v ./blockchain/core -run TestContract

# Bridge
go test -v ./blockchain/bridge
go test -v ./blockchain/api -run TestBridge

# JSON-RPC
go test -v ./blockchain/api/jsonrpc
```

## Benchmarks

```bash
go test -bench=. ./crypto/dilithium
go test -bench=. ./vrf
go test -bench=. -benchtime=10s ./blockchain/core
go test -bench=. ./qwvm
```

Reference numbers in [../resources/benchmarks.md](/quantumwing/resources/benchmarks.md).

## Integration tests

End-to-end shell tests live under `scripts/`. They spin up a local three-layer stack and assert observable behaviour:

```bash
./scripts/test-integration-final.sh    # slashing API → consensus → storage
./scripts/test-api-endpoints.sh        # REST contract surface
./scripts/test-block-backfill.sh       # P2P backfill on cold-start
./scripts/test-chain-sync.sh           # multi-node sync
./scripts/test-alpha-wallet-format.sh  # v2 BIP-39 wallet round-trip
```

These tests assume:

* A clean port set (8080, 8545, 8546, 9000)
* `make build` has run
* Roughly 4 GB free RAM

Run them sequentially, not in parallel — they compete for ports.

## Loadgen / chaos

```bash
# Sustained 2,000 TPS for 1 minute
./scripts/loadtest-2k-tps.sh

# Validator chaos restart
./ops/systemd/chaos-restart.sh
```

## Conventions

* New code MUST come with a unit test or a documented reason for not.
* A bug fix MUST add a regression test that fails on the prior code and passes on the fix.
* Tests live alongside source: `foo.go` → `foo_test.go`. Integration tests under `scripts/` shell out to the binaries.
* Test names: `TestComponent_Behavior_Condition` (`TestSlashingManager_DoubleAttest_BansForSevenDays`).
* Table-driven tests are preferred for any function with multiple branches.

## CI

GitHub Actions runs:

```
1. go vet ./...
2. go test -race -count=1 -timeout=10m ./...
3. explorer: pnpm typecheck && pnpm lint
4. on master only: build all binaries, attach to release
```

Before pushing a PR, run `./scripts/test-all.sh` locally.

## Known flaky tests

| Test                                            | Status                  | Workaround         |
| ----------------------------------------------- | ----------------------- | ------------------ |
| `blockchain/storage::TestPruner_CursorPersists` | passes \~95% of runs    | retry once         |
| `blockchain/p2p::TestGossipSub_*`               | intermittent on slow CI | bump test timeout  |
| `blockchain/consensus/por::TestForkChoice_*`    | pre-existing failure    | tracked separately |

A flaky test is not a green light to disable it. File a tracking issue and add `t.Skip("flaky — see issue #N")` only if it is blocking.

## Code paths

* `scripts/test-all.sh` — CI wrapper
* `scripts/test-integration-final.sh` — end-to-end slashing
* `scripts/test-api-endpoints.sh` — REST coverage
* `Makefile::test`, `Makefile::test-coverage`
* `.github/workflows/` — CI configuration

## Related

* [building-from-source.md](/quantumwing/development/building-from-source.md)
* [contributing.md](/quantumwing/development/contributing.md) — PR conventions
* [../TESTING.md](https://github.com/dolfrin/QuantumWing/blob/master/docs/TESTING.md) — full coverage matrix
* [../resources/benchmarks.md](/quantumwing/resources/benchmarks.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://quantumwing.gitbook.io/quantumwing/development/testing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.