From dcdd46c3fce206e2970e2beafea27254afa6139f Mon Sep 17 00:00:00 2001
From: Nick Alexander <ncalexan@users.noreply.github.com>
Date: Wed, 1 Feb 2017 15:03:09 -0800
Subject: [PATCH] Created Transacting: EDN test format (markdown)

---
 Transacting:-EDN-test-format.md | 43 +++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 Transacting:-EDN-test-format.md

diff --git a/Transacting:-EDN-test-format.md b/Transacting:-EDN-test-format.md
new file mode 100644
index 0000000..9b594e4
--- /dev/null
+++ b/Transacting:-EDN-test-format.md
@@ -0,0 +1,43 @@
+The Rust and Clojure{Script} implementations of Mentat share part of their test suites.  Tests in this suite are text files in EDN format that label what is being tested, represent assertions to apply to a bootstrapped store, and capture expectations of what parts of the store should look like after the assertions are transacted.
+
+## Format
+
+The top-level element should be a vector of transactions.  Each transaction should be a map with the following required keys:
+
+| key | type | description | example |
+| --- | --- | --- | --- |
+| `:test/label` | string | a brief description of what the transaction is testing | ":db/add ignores existing datoms" |
+| `:test/assertions` | vector | valid Mentat transaction data | `[[:db/add E A V]]` |
+
+and at least one of the following optional keys:
+
+| key | type | description | example |
+| --- | --- | --- | --- |
+| `:test/expectedtransaction` | set | transacted datoms, w/ `added` | `#{[?tx1 :db/txInstant ?ms1 ?tx1 true]}` |
+| `:test/expecteddatoms` | set | all datoms after bootstrap, w/o `:db/txInstant` datoms | `#{[E A V ?tx1]}` |
+
+## Special values
+
+Transaction identifiers are replaced with `?txN`, where `N` counts the transaction number after the initial bootstrap transaction.  Therefore, the first tested transaction is `?tx1`, the next `?tx2`, and so on.  Transaction timestamps are replaced with `?mxN`, where `N` is as above.
+
+Therefore every expected transaction should include a datom like:
+```edn
+[?txN :db/txInstant ?msN ?txN true]
+```
+
+## Example
+
+```edn
+;; This is EDN, so comments are allowed.
+[{:test/label "can insert two :db.cardinality/one datoms"
+  :test/assertions
+  [[:db/add 100 :db/ident :keyword/value1]
+   [:db/add 101 :db/ident :keyword/value2]]
+  :test/expectedtransaction
+  #{[100 :db/ident :keyword/value1 ?tx1 true]
+    [101 :db/ident :keyword/value2 ?tx1 true]
+    [?tx1 :db/txInstant ?ms1 ?tx1 true]}
+  :test/expecteddatoms
+  #{[100 :db/ident :keyword/value1]
+    [101 :db/ident :keyword/value2]}}]
+```
\ No newline at end of file