@@ -0,0 +1,80 @@
1++++
2+title = "Writing Aqua Tests"
3+weight = 37
4+template = "doc.html"
5++++
6+
7+# Concepts
8+
9+Aqua (short for "aquarium", alluding to the idea that you're running
10+multiple ships in a safe, artificial environment and watching them
11+carefully) is an app that lets you run one or more virtual ships from
12+within a single host.
13+
14+pH is a library of functions designed to make it easy to write
15+integration tests using Aqua.
16+
17+# First test
18+
19+To run your first pH test, run the following commands:
20+
21+```
22+|start %aqua
23+:aqua +solid
24+-ph-add
25+```
26+
27+This will start Aqua, compile a new kernel for it, and then compile and
28+run /ted/ph/add.hoon. Here are the contents of that file:
29+
30+```
31+/- spider
32+/+ *ph-io
33+=, strand=strand:spider
34+^- thread:spider
35+|= [=bowl:spider args=vase]
36+=/ m (strand ,vase)
37+;< ~ bind:m start-simple
38+;< ~ bind:m (raw-ship ~bud ~)
39+;< ~ bind:m (dojo ~bud "[%test-result (add 2 3)]")
40+;< ~ bind:m (wait-for-output ~bud "[%test-result 5]")
41+;< ~ bind:m end-simple
42+(pure:m *vase)
43+```
44+
45+There's a few lines of boilerplate, with three important lines defining
46+the test.
47+
48+```
49+;< ~ bind:m (raw-ship ~bud ~)
50+;< ~ bind:m (dojo ~bud "[%test-result (add 2 3)]")
51+;< ~ bind:m (wait-for-output ~bud "[%test-result 5]")
52+```
53+
54+We boot a ship with `+raw-ship`. In this case the ship we are booting will be `~bud`. These ships exist in a virtual environment so you could use any valid `@p`.
55+
56+Next we enter some commands with `+dojo`, and then we wait until we get a line that includes some expected output. Each of these commands we need to specify the ship we want to run on.
57+
58+Many tests can be created with nothing more than these simple tools.
59+Try starting two ships and having one send a `|hi` to the other, and
60+check that it arrives.
61+
62+Many more complex tests can be created, including file changes, personal
63+breaches, mock http clients or servers, or anything you can imagine.
64+Check out `/lib/ph/io.hoon` for other available functions, and look at
65+other tests in `/ted/ph/` for inspiration.
66+
67+# Reference
68+
69+Aqua has the following commands:
70+
71+`:aqua +solid` Compiles a "pill" (kernel) for the guest ships and loads it into Aqua.
72+
73+`:aqua [%swap-files ~]` modifies the pill to use the files you have in
74+your filesystem without rebuilding the whole pill. For example, if you
75+change an app and you want to test the new version, you must install it
76+in the pill. This command will do that.
77+
78+`:aqua [%swap-vanes ~[%a]]` Modifies the pill to load a new version of a
79+vane (`%a` == Ames in this example, but it can be any list of vanes).
80+This is faster than running `:aqua +solid`.