Merge pull request #48 from fermyon/basic-docs

Add basic docs for spin-test and Rust SDK

README.md

@@ -1,7 +1,43 @@
 # `spin-test`
 
-`spin-test` is a plugin for Spin that allows running tests written in WebAssembly against a Spin application where all Spin and WASI APIs are configurable and assertable mocks.
+`spin-test` is a plugin for Spin that runs tests written in WebAssembly against a Spin application where all Spin and WASI APIs are configurable and assertable mocks.
+
+## Usage
+
+### Create a Spin App
+
+`spin-test` runs tests against a Spin application. As such, you'll need a Spin app to test against. You can find more information on creating Spin applications [here](https://developer.fermyon.com/spin/v2/quickstart).
+
+### Create a `spin-test` test
+
+Next you'll need a `spin-test` test compiled to a WebAssembly component.
+
+There is currently first class support for Rust through the [`spin-test` Rust SDK](./crates/spin-test-sdk/), but any language with support for writing WebAssembly components can be used as long as the `fermyon:spin-test/test` world is targeted. You can find the definition of this world in [here](./host-wit/world.wit).
+
+You can see examples of tests written in a variety of languages in [the examples](./examples/).
+
+### Configure `spin-test`
+
+Next, we'll need to tell `spin-test` where our test lives and how to build it. We do this from inside the `spin.toml` manifest. Let's imagine our app has a component named "my-component" that we want to test. In the `spin.toml` manifest we can add the following configuration:
+
+```toml
+[component.my-component.tool.spin-test]
+# A relative path to where the built test component binary will live.
+source = "target/wasm32-wasi/release/test.wasm"
+# A command for building the target component.
+build = "cargo component build --release"
+# The directory where the `build` command should be run.
+dir = "../../test-rs"
+```
+
+### Run `spin-test`
+
+Finally, we're ready for our test to be run. We can do this simply by invoking `spin-test` from the directory where our Spin application lives:
+
+```bash
+spin-test
+```
 
 ## Examples
 
-See the `examples` directory for how this works in practice.
+See the [`examples`](./examples/) directory for a few examples of `spin-test` tests that test the apps in the [`apps`](./examples/apps/) directory.

crates/spin-test-sdk/README.md

@@ -0,0 +1,34 @@
+# `spin-test` Rust SDK
+
+A library for writing `spin-test` tests in Rust.
+
+## Usage
+
+The `spin-test` Rust SDK allows you to annotate functions as `spin-test` tests that will automatically be exposed to `spin-test` as tests to be run: 
+
+```rust
+use spin_test_sdk::{bindings::wasi::http, spin_test};
+
+#[spin_test]
+fn my_test() {
+    // Make a request to the Spin application
+    let request = http::types::OutgoingRequest::new(http::types::Headers::new());
+    request.set_path_with_query(Some("/?user_id=123")).unwrap();
+    let response = spin_test_sdk::perform_request(request);
+
+    // Assert response status
+    assert_eq!(response.status(), 200);
+}
+```
+
+The `spin-test` Rust SDK gives access to the `fermyon:spin/test` world through the `bindings` module. You can use the various types in that module to customize your test scenario, make requests against the Spin application, and make assertions about the state of the world before and after the request has been made.
+
+As an example, in the following code, we are seeding the `key-value` store our Spin app has access to with some values to test that our app can handle when the key-value store is in such a state:
+
+```rust
+    // Open the store
+    let key_value = key_value::Store::open("default");
+    // Set state of the key-value store
+    key_value.set("123", "abc");
+    // Now make our request to the Spin app...
+```

examples/README.md

@@ -6,6 +6,5 @@ The examples folder contains multiple examples of `spin-test` compliant tests al
 
 Running a test against a Spin application requires the following steps:
 
-* Build the test wasm binary. Each test directory contains a README.md file with instructions on how to build the test since this is language dependent.
-* Build the Spin application. Change into the app directory where the app you want to test lives, and run `spin build`.
-* Run `spin-test`. From inside the directory for the app you're testing, run `spin-test $PATH_TO_TEST_BINARY`
+* **Build the Spin application**: Change into the app directory where the app you want to test lives, and run `spin build`.
+* **Run `spin-test`**: From inside the directory for the app you're testing, run `spin-test`.

examples/test-rs/README.md

@@ -5,5 +5,5 @@
 Building this test requires [cargo-component](https://github.com/bytecodealliance/cargo-component) to be installed.
 
 ```
-cargo component build
+cargo component build --release
 ```