Canonical: https://solanashreds.xyz/blog/regression-tests-for-decoders

# Golden fixtures: regression tests that catch a broken decoder

A decoder change that silently alters one field in one program's output is the hardest bug to notice. Golden fixtures make every such change show up as a diff before it ships.

A golden fixture pairs a captured input with decoded output you have checked by hand or against RPC. Keep real transactions in each format, store their expected decoded rows next to them, and diff the decoder's output in CI on every change, updating the expected files only when a program's layout changes on purpose.

## Capturing inputs you can replay

A decoder has two kinds of input, and it is worth keeping fixtures of both.

**Transaction bytes.** The simplest fixture is one raw transaction. `getBlock` and `getTransaction` can return transactions as base64 encoded bytes; ask for `maxSupportedTransactionVersion` 1 so that v0 and v1 transactions come back as well as legacy ones. Save the bytes with the slot and signature they came from. These fixtures test everything from message parsing upward and are small enough to keep in the repository.

**Packet captures.** To test the stages below the transaction (grouping, recovery, deshredding), you need the datagrams themselves. Record them on your receiver with a packet capture tool, for example `tcpdump -w` filtered to your UDP port, for a few slots. Packet captures are large and contain real traffic, so keep them out of the repository and in your own storage, and record a checksum in the repository instead.

Pick inputs on purpose rather than at random. You want each message format, each program you decode, transactions that failed on chain, transactions using lookup tables, and at least one slot that needed erasure recovery.

## A fixture directory that stays readable

| Path | Holds |
|---|---|
| `fixtures/tx/<signature>.bin` | Raw transaction bytes, exactly as decoded from the stream or returned by RPC |
| `fixtures/tx/<signature>.meta.json` | Slot, format, source, the date captured, and why this fixture exists |
| `fixtures/tx/<signature>.expected.json` | The decoded output your decoder must produce, sorted and stable |
| `fixtures/slots/<slot>.sha256` | Checksum of a packet capture kept in external storage |
| `fixtures/slots/<slot>.expected.json` | Signatures in entry order for that slot, as your pipeline should emit them |

Write a reason in every meta file. A year later, "covers a v0 swap whose pool sits in a lookup table" tells a reviewer why this fixture must never be deleted.

## Writing expected output you can trust

An expected file is only as good as the check behind it. Generate it from your decoder once, then verify it against an independent source before you commit it.

- **Account keys.** For v0 transactions, `getTransaction` returns the addresses loaded from lookup tables in its metadata. Compare them with your decoder's resolved key list; this is the most common place for silent errors.
- **Instruction arguments.** Compare amounts and named accounts with the program's own IDL or source, or with an explorer's decoded view for the same signature.
- **Order.** For slot fixtures, compare the transaction order with the block returned by `getBlock` for that slot.

Make the output deterministic: sort keys, fix the number format, and leave out anything that changes between runs, such as timestamps of when you decoded.

## Running fixtures in CI

1. For every transaction fixture, run the decoder on the `.bin` file and write its output in the same canonical form as the expected file.
2. Diff the two. Any difference fails the build and prints the field that changed.
3. For slot fixtures, fetch the capture by checksum from storage, replay it through the receiver stages and compare the emitted signature list.
4. Allow an explicit update mode, set by an environment variable, that rewrites expected files. Never run it automatically.
5. Require that a pull request which changes expected files says why, in the meta file or the description.

## Refreshing after program upgrades

Programs change their layouts. When one does, transactions before the upgrade still follow the old layout, and transactions after it follow the new one. Do not overwrite the old fixtures: they protect your decoder's handling of history. Add new fixtures from after the upgrade, record the slot ranges each layout covers, and make sure the decoder chooses the layout by slot. [IDL drift](https://solanashreds.xyz/blog/idl-drift) covers how to version those layouts, and [fuzzing the parser](https://solanashreds.xyz/blog/your-decoder-will-meet-garbage) adds crash inputs to the same fixture set.

## What golden fixtures cannot catch

Fixtures only test the inputs you chose. A program you never captured, or a layout change that happens after your last capture, will not show up until you add a fixture for it. They also freeze your understanding at the moment you wrote the expected file; if that understanding was wrong and RPC agreed for the wrong reason, the fixture protects the bug. Recheck a sample of expected files against [confirmed data from RPC](https://solanashreds.xyz/docs/pipeline/reconcile) whenever you change how you interpret a program.

## Related pages

[Decoder test fixtures](https://solanashreds.xyz/docs/decode/test-fixtures) gives the how-to with the shared fixture set. If you need to keep packet captures for longer, [archive formats](https://solanashreds.xyz/compare/shred-archive-formats) compares the options. The [transaction structure page](https://solanashreds.xyz/learn/solana-transaction-structure) explains the fields your expected files should cover. Fixtures are easiest to collect from your own receiver, so a [Standard Shreds](https://solanashreds.xyz/standard-shreds) destination is a good place to record them.

Refresh the fixtures for a program as soon as [an upgrade instruction for it shows up](https://solanashreds.xyz/blog/watching-program-upgrades) in the stream.

Test the filter stage as well: [where to place the program filter](https://solanashreds.xyz/blog/filter-early) changes which fixtures matter.
