From 4ccd304603c351a6ca2c8fd2e3ef33d795f4bc05 Mon Sep 17 00:00:00 2001
From: protolambda <proto@protolambda.com>
Date: Fri, 24 May 2019 01:03:21 +0200
Subject: [PATCH] docs for sanity tests

---
 specs/test_formats/sanity/README.md |  7 +++++++
 specs/test_formats/sanity/blocks.md | 19 +++++++++++++++++++
 specs/test_formats/sanity/slots.md  | 24 ++++++++++++++++++++++++
 3 files changed, 50 insertions(+)
 create mode 100644 specs/test_formats/sanity/README.md
 create mode 100644 specs/test_formats/sanity/blocks.md
 create mode 100644 specs/test_formats/sanity/slots.md

diff --git a/specs/test_formats/sanity/README.md b/specs/test_formats/sanity/README.md
new file mode 100644
index 000000000..20b36208a
--- /dev/null
+++ b/specs/test_formats/sanity/README.md
@@ -0,0 +1,7 @@
+# Sanity tests
+
+The aim of the sanity tests is to set a base-line on what really needs to pass, i.e. the essentials.
+
+There are two handlers, documented individually:
+- [`slots`](./slots.md): transitions of one or more slots (and epoch transitions within)
+- [`blocks`](./blocks.md): transitions triggered by one or more blocks
diff --git a/specs/test_formats/sanity/blocks.md b/specs/test_formats/sanity/blocks.md
new file mode 100644
index 000000000..696813740
--- /dev/null
+++ b/specs/test_formats/sanity/blocks.md
@@ -0,0 +1,19 @@
+# Sanity blocks testing
+
+Sanity tests to cover a series of one or more blocks being processed, aiming to cover common changes.
+
+## Test case format
+
+```yaml
+description: string    -- description of test case, purely for debugging purposes
+bls_required: bool     -- optional, true if the test validity is strictly dependent on BLS being ON. False otherwise.
+bls_ignored: bool      -- optional, true if the test validity is strictly dependent on BLS being OFF. False otherwise.
+pre: BeaconState       -- state before running through the transitions triggered by the blocks.
+blocks: [BeaconBlock]  -- blocks to process, in given order, following the main transition function (i.e. process slot and epoch transitions in between blocks as normal)
+post: BeaconState      -- state after applying all the transitions triggered by the blocks.
+```
+
+## Condition
+
+The resulting state should match the expected `post` state, or if the `post` state is left blank,
+ the handler should reject the series of blocks as invalid.
diff --git a/specs/test_formats/sanity/slots.md b/specs/test_formats/sanity/slots.md
new file mode 100644
index 000000000..e8961608d
--- /dev/null
+++ b/specs/test_formats/sanity/slots.md
@@ -0,0 +1,24 @@
+# Sanity slots testing
+
+Sanity tests to cover a series of one or more empty-slot transitions being processed, aiming to cover common changes.
+
+## Test case format
+
+```yaml
+description: string    -- description of test case, purely for debugging purposes
+bls_required: bool     -- optional, true if the test validity is strictly dependent on BLS being ON. False otherwise.
+bls_ignored: bool      -- optional, true if the test validity is strictly dependent on BLS being OFF. False otherwise.
+pre: BeaconState       -- state before running through the transitions.
+slots: N               -- amount of slots to process, N being a positive numer.
+post: BeaconState      -- state after applying all the transitions.
+```
+
+The transition with pure time, no blocks, is known as `state_transition_to(state, slot)` in the spec.
+This runs state-caching (pure slot transition) and epoch processing (every E slots).
+
+To process the data, call `state_transition_to(pre, pre.slot + N)`. And see if `pre` mutated into the equivalent of `post`.
+
+
+## Condition
+
+The resulting state should match the expected `post` state.