update example

examples/incr/std.output

@@ -3,4 +3,4 @@
         std_test.go:34: expected x to be 2, is 3 instead
 FAIL
 exit status 1
-FAIL	github.com/jordanorelli/tea/examples/incr	0.001s
+FAIL	github.com/jordanorelli/tea/examples/incr	0.002s

examples/incr/tea.output

@@ -1,2 +1,17 @@
-PASS
-ok  	github.com/jordanorelli/tea/examples/incr	0.001s
+--- FAIL: TestOnce (0.00s)
+    --- FAIL: TestOnce/testInt (0.00s)
+        tea_test.go:15: saving to future tests X = 1
+        --- FAIL: TestOnce/testInt/testIncr (0.00s)
+            tea_test.go:15: saving to future tests X = 1
+            tea_test.go:24: loaded from parent tests X = 1
+            tea_test.go:29: saving to future tests X = 2
+            --- FAIL: TestOnce/testInt/testIncr/testIncr (0.00s)
+                tea_test.go:15: saving to future tests X = 1
+                tea_test.go:24: loaded from parent tests X = 1
+                tea_test.go:29: saving to future tests X = 2
+                tea_test.go:24: loaded from parent tests X = 1
+                tea_test.go:27: expected X to be 3, is 2 instead
+                tea_test.go:29: saving to future tests X = 2
+FAIL
+exit status 1
+FAIL	github.com/jordanorelli/tea/examples/incr	0.002s

examples/incr/tea_test.go

@@ -8,32 +8,68 @@ import (
 )
 
 type testInt struct {
+	// the "save" struct tag instructs tea to save this field for future tests.
 	X int `tea:"save"`
 }
 
-func (testInt) Run(t *testing.T) {}
+func (test *testInt) Run(t *testing.T) {
+	t.Logf("saving to future tests X = %d", test.X)
+}
 
 type testIncr struct {
-	X      int `tea:"load"`
+	// the "load" struct tag instructs tea to load the value of this field from
+	// previous tests in this run. Like before, we also use a "save" tag.
+	X      int `tea:"load,save"`
 	expect int
 }
 
 func (test *testIncr) Run(t *testing.T) {
+	t.Logf("loaded from parent tests X = %d", test.X)
 	test.X++
 	if test.X != test.expect {
 		t.Errorf("expected X to be %d, is %d instead", test.expect, test.X)
 	}
+	t.Logf("saving to future tests X = %d", test.X)
 }
 
 func TestOnce(t *testing.T) {
+	// we use testInt with X set to 1 as our starting test.
 	root := tea.New(&testInt{X: 1})
+
+	// after that test passes, we want to run a test of type testIncr.
 	root.Child(&testIncr{expect: 2})
+
 	tea.Run(t, root)
 }
 
 func TestTwice(t *testing.T) {
+	// same setup as in TestOnce
 	root := tea.New(&testInt{X: 1})
+
+	// just like before, we want to run a testIncr test after the root test
+	// passes.
 	root.Child(&testIncr{expect: 2})
+
+	// This testIncr and the other testIncr are siblings, since we called Child
+	// from the same node.
 	root.Child(&testIncr{expect: 2})
+
+	tea.Run(t, root)
+}
+
+func TestTwiceSeries(t *testing.T) {
+	// we use testInt with X set to 1 as our starting test.
+	root := tea.New(&testInt{X: 1})
+
+	// by now this should look familiar. The difference here is that we save
+	// the newly created node in the tree.
+	two := root.Child(&testIncr{expect: 2})
+
+	// adding a child to two here
+	two.Child(&testIncr{expect: 3})
+
+	// but of course, we can still add new children to the root.
+	root.Child(&testIncr{expect: 2})
+
 	tea.Run(t, root)
 }

tree.go

@@ -10,6 +10,11 @@ import (
 // provided node and descending to all of its children. All of its parent nodes
 // will also be run since they are prerequisites, but none of its sibling node
 // will be executed.
+//
+// Since Run will walk all of the descendents of the provided node, a typical
+// usage would be to write a top-level Go test which is a single tree of tea
+// Test values. You would then call Run just once, by supplying to Run the root
+// node of your tree.
 func Run(t *testing.T, tree *Tree) {
 	t.Run(tree.name, func(t *testing.T) {
 		history, _ := exec(t, tree)