update test format docs with new test structure

specs/test_formats/bls/aggregate_pubkeys.md

@@ -4,6 +4,8 @@ A BLS pubkey aggregation combines a series of pubkeys into a single pubkey.
 
 ## Test case format
 
+The test data is declared in a `data.yaml` file:
+
 ```yaml
 input: List[BLS Pubkey] -- list of input BLS pubkeys
 output: BLS Pubkey -- expected output, single BLS pubkey

specs/test_formats/bls/aggregate_sigs.md

@@ -4,6 +4,8 @@ A BLS signature aggregation combines a series of signatures into a single signat
 
 ## Test case format
 
+The test data is declared in a `data.yaml` file:
+
 ```yaml
 input: List[BLS Signature] -- list of input BLS signatures
 output: BLS Signature -- expected output, single BLS signature

specs/test_formats/bls/msg_hash_g2_compressed.md

@@ -4,6 +4,8 @@ A BLS compressed-hash to G2.
 
 ## Test case format
 
+The test data is declared in a `data.yaml` file:
+
 ```yaml
 input: 
   message: bytes32

specs/test_formats/bls/msg_hash_g2_uncompressed.md

@@ -4,6 +4,8 @@ A BLS uncompressed-hash to G2.
 
 ## Test case format
 
+The test data is declared in a `data.yaml` file:
+
 ```yaml
 input:
   message: bytes32

specs/test_formats/bls/priv_to_pub.md

@@ -4,6 +4,8 @@ A BLS private key to public key conversion.
 
 ## Test case format
 
+The test data is declared in a `data.yaml` file:
+
 ```yaml
 input: bytes32 -- the private key
 output: bytes48 -- the public key

specs/test_formats/bls/sign_msg.md

@@ -4,6 +4,8 @@ Message signing with BLS should produce a signature.
 
 ## Test case format
 
+The test data is declared in a `data.yaml` file:
+
 ```yaml
 input:
   privkey: bytes32 -- the private key used for signing

specs/test_formats/epoch_processing/README.md

@@ -7,13 +7,27 @@ Hence, the format is shared between each test-handler. (See test condition docum
 
 ## Test case format
 
+### `meta.yaml`
+
 ```yaml
-description: string    -- description of test case, purely for debugging purposes
+description: string    -- Optional description of test case, purely for debugging purposes.
+                          Tests should use the directory name of the test case as identifier, not the description.
 bls_setting: int       -- see general test-format spec.
-pre: BeaconState       -- state before running the sub-transition
-post: BeaconState      -- state after applying the epoch sub-transition.
 ```
 
+### `pre.yaml`
+
+A YAML-encoded `BeaconState`, the state before running the epoch sub-transition.
+
+A `pre.ssz` is also available as substitute.
+
+
+### `post.yaml`
+
+A YAML-encoded `BeaconState`, the state after applying the epoch sub-transition.
+
+A `post.ssz` is also available as substitute.
+
 ## Condition
 
 A handler of the `epoch_processing` test-runner should process these cases, 

specs/test_formats/genesis/initialization.md

@@ -4,14 +4,36 @@ Tests the initialization of a genesis state based on Eth1 data.
 
 ## Test case format
 
-```yaml
+### `eth1_block_hash.yaml`
-description: string            -- description of test case, purely for debugging purposes
+
-bls_setting: int               -- see general test-format spec.
+A `Bytes32` hex encoded, with prefix 0x. The root of the Eth-1 block.
-eth1_block_hash: Bytes32       -- the root of the Eth-1 block, hex encoded, with prefix 0x
+
-eth1_timestamp: int            -- the timestamp of the block, in seconds.
+A `eth1_block_hash.ssz` is available as substitute.
-deposits: [Deposit]            -- list of deposits to build the genesis state with
+
-state: BeaconState             -- the expected genesis state.
+### `eth1_timestamp.yaml`
+
+An integer. The timestamp of the block, in seconds.
+
+### `meta.yaml`
+
+A yaml file to help read the deposit count:
+
 ```
+deposits_count: int    -- Amount of deposits.
+```
+
+## `deposits_<index>.yaml`
+
+A series of files, with `<index>` ranging `[0, deposit_count)`.
+Each deposit is also available as `deposits_<index>.ssz`
+
+###  `state.yaml`
+
+The expected genesis state.
+
+Also available as `state.ssz`.
+
+## Processing
 
 To process this test, build a genesis state with the provided `eth1_block_hash`, `eth1_timestamp` and `deposits`:
 `initialize_beacon_state_from_eth1(eth1_block_hash, eth1_timestamp, deposits)`,

specs/test_formats/genesis/validity.md

@@ -4,12 +4,18 @@ Tests if a genesis state is valid, i.e. if it counts as trigger to launch.
 
 ## Test case format
 
-```yaml
+### `genesis.yaml`
-description: string    -- description of test case, purely for debugging purposes
+
-bls_setting: int       -- see general test-format spec.
+A `BeaconState`, the state to validate as genesis candidate.
-genesis: BeaconState   -- state to validate.
+
-is_valid: bool         -- true if the genesis state is deemed valid as to launch with, false otherwise.
+Also available as `genesis.ssz`. 
-```
+
+### `is_valid.yaml`
+
+A boolean, true if the genesis state is deemed valid as to launch with, false otherwise.
+
+
+## Processing
 
 To process the data, call `is_valid_genesis_state(genesis)`.
 

specs/test_formats/operations/README.md

@@ -4,14 +4,33 @@ The different kinds of operations ("transactions") are tested individually with
 
 ## Test case format
 
+### `meta.yaml`
+
 ```yaml
-description: string                    -- description of test case, purely for debugging purposes
+description: string    -- Optional description of test case, purely for debugging purposes.
-bls_setting: int                       -- see general test-format spec.
+                          Tests should use the directory name of the test case as identifier, not the description.
-pre: BeaconState                       -- state before applying the operation
+bls_setting: int       -- see general test-format spec.
-<operation-name>: <operation-object>   -- the YAML encoded operation, e.g. a "ProposerSlashing", or "Deposit".
-post: BeaconState                      -- state after applying the operation. No value if operation processing is aborted.
 ```
 
+### `pre.yaml`
+
+A YAML-encoded `BeaconState`, the state before applying the operation.
+
+A `pre.ssz` is also available as substitute.
+
+### `<operation-name>.yaml`
+
+A YAML-encoded operation object, e.g. a `ProposerSlashing`, or `Deposit`.
+
+A `<operation-name>.ssz` is also available as substitute.
+
+### `post.yaml`
+
+A YAML-encoded `BeaconState`, the state after applying the operation. No value if operation processing is aborted.
+
+A `post.ssz` is also available as substitute.
+
+
 ## Condition
 
 A handler of the `operations` test-runner should process these cases,
@@ -24,7 +43,7 @@ Operations:
 |-------------------------|----------------------|----------------------|--------------------------------------------------------|
 | `attestation`           | `Attestation`        | `attestation`        | `process_attestation(state, attestation)`              |
 | `attester_slashing`     | `AttesterSlashing`   | `attester_slashing`  | `process_attester_slashing(state, attester_slashing)`  |
-| `block_header`          | `Block`              | `block`              | `process_block_header(state, block)`                   |
+| `block_header`          | `Block`              | **`block**           | `process_block_header(state, block)`                   |
 | `deposit`               | `Deposit`            | `deposit`            | `process_deposit(state, deposit)`                      |
 | `proposer_slashing`     | `ProposerSlashing`   | `proposer_slashing`  | `process_proposer_slashing(state, proposer_slashing)`  |
 | `transfer`              | `Transfer`           | `transfer`           | `process_transfer(state, transfer)`                    |