tests: Document linearizability tests

Signed-off-by: Marek Siarkowicz <siarkowicz@google.com>

.github/workflows/linearizability.yaml

@@ -9,7 +9,7 @@ jobs:
       with:
         go-version: "1.19.3"
     - run: |
-        pushd tools/mod; go install go.etcd.io/gofail; popd
+        make install-gofail
         mkdir -p /tmp/linearizability
         FAILPOINTS=true make build
         cat server/etcdserver/raft.fail.go

Makefile

@@ -105,6 +105,11 @@ verify-proto-annotations:
 verify-genproto:
 	PASSES="genproto" ./scripts/test.sh
 
+# Install dependencies
+
+install-gofail:
+	cd tools/mod; go install go.etcd.io/gofail
+
 
 # Cleanup
 

tests/linearizability/README.md

@@ -0,0 +1,24 @@
+# etcd Linearizability Testing
+
+This directory consists of etcd linearizability tests, that validate the correct
+behavior of etcd under various system and network malfunctions.
+
+This is done by comparing how real etcd cluster behaves versus an in memory model of etcd.
+During the test we continuously inject different types of failures and validate etcd correctness.
+
+TODO: How linearizability is used to validate tests
+
+## Run locally
+
+1. Build etcd with failpoints (can be skipped if you )
+    ```bash
+    make install-gofail
+    FAILPOINTS=true make build
+    ```
+2. Run linearizability tests
+
+    ```bash
+    make test-linearizability
+    ```
+
+TODO: How to validate results