From 6b701a6c8b0dedb097163902c19d07d68f024cdd Mon Sep 17 00:00:00 2001
From: protolambda <proto@protolambda.com>
Date: Fri, 12 Apr 2019 23:59:19 +1000
Subject: [PATCH] update tests format docs

---
 specs/test_formats/README.md     | 26 +++++++++++++++++++-------
 specs/test_formats/ssz/README.md | 15 +++++++++++++++
 2 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/specs/test_formats/README.md b/specs/test_formats/README.md
index 71e72f0cb..53973495d 100644
--- a/specs/test_formats/README.md
+++ b/specs/test_formats/README.md
@@ -17,8 +17,17 @@ This document defines the YAML format and structure used for ETH 2.0 testing.
 
 Ethereum 2.0 uses YAML as the format for all cross client tests. This document describes at a high level the general format to which all test files should conform.
 
+### Test-case formats
+
 The particular formats of specific types of tests (test suites) are defined in separate documents.
 
+Test formats:
+- [`bls`](./bls/README.md)
+- [`operations`](./operations/README.md)
+- [`shuffling`](./shuffling/README.md)
+- [`ssz`](./ssz/README.md)
+- More formats are planned, see tracking issues for CI/testing
+
 ## Glossary
 
 - `generator`: a program that outputs one or more `suite` files.
@@ -167,11 +176,14 @@ To prevent parsing of hundreds of different YAML files to test a specific test t
  or even more specific, just a handler, tests should be structured in the following nested form: 
 
 ```
-.                        <--- root of eth2.0 tests repository
-├── bls                  <--- collection of handler for a specific test-runner, example runner: "bls"
-│   ├── signing          <--- collection of test suites for a specific handler, example handler: "signing". If no multiple handlers, use a dummy folder (e.g. "main"), and specify that in the yaml.
-│   │   ├── sign_msg.yml <--- an entry list of test suites
-│   │   ...              <--- more suite files (optional)
-│   ...                  <--- more handlers
-...                      <--- more test types
+.                             <--- root of eth2.0 tests repository
+├── bls                       <--- collection of handler for a specific test-runner, example runner: "bls"
+│   ├── verify_msg            <--- collection of test suites for a specific handler, example handler: "verify_msg". If no multiple handlers, use a dummy folder (e.g. "core"), and specify that in the yaml.
+│   │   ├── verify_valid.yml    .
+│   │   ├── special_cases.yml   . a list of test suites
+│   │   ├── domains.yml         .
+│   │   ├── invalid.yml         .
+│   │   ...                   <--- more suite files (optional)
+│   ...                       <--- more handlers
+...                           <--- more test types
 ```
diff --git a/specs/test_formats/ssz/README.md b/specs/test_formats/ssz/README.md
index e69de29bb..72ba7dac1 100644
--- a/specs/test_formats/ssz/README.md
+++ b/specs/test_formats/ssz/README.md
@@ -0,0 +1,15 @@
+# SSZ tests
+
+SSZ has changed throughout the development of ETH 2.0.
+
+## Contents
+
+A minimal but useful series of tests covering `uint` encoding and decoding is provided.
+This is a direct port of the older SSZ `uint` tests (minus outdated test cases).
+
+[uint test format](./uint.md).
+
+Note: the current phase-0 spec does not use larger uints, and uses byte vectors (fixed length) instead to represent roots etc.
+The exact uint lengths to support may be redefined in the future.
+
+Extension of the SSZ tests collection is planned, see CI/testing issues for progress tracking.