@@ -0,0 +1,80 @@
2+title = "Writing Aqua Tests"
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
14+pH is a library of functions designed to make it easy to write
15+integration tests using Aqua.
19+To run your first pH test, run the following commands:
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:
33+=, strand=strand:spider
35+|= [=bowl:spider args=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
45+There's a few lines of boilerplate, with three important lines defining
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]")
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`.
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.
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.
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.
69+Aqua has the following commands:
71+`:aqua +solid` Compiles a "pill" (kernel) for the guest ships and loads it into Aqua.
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.
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`.