feat: add unit test feature

Signed-off-by: Andrew Steurer <94206073+asteurer@users.noreply.github.com>

Author: asteurer

.gitignore

@@ -9,4 +9,3 @@ examples/*/go.mod
 examples/*/go.sum
 examples/*/wasi_*
 examples/*/wit_*
-examples/*/export_wasi*

examples/unit_tests/README.md

@@ -0,0 +1,37 @@
+# Unit Tests
+
+There are two scenarios that componentize-go supports for building unit tests:
+- [Basic unit tests](#basic-unit-tests) (Can be run using the wasmtime cli tool)
+- [Guest-Host unit tests](#guest-host-unit-tests) (requires a custom runtime implementation)
+
+We recognize that building unit tests with Go and WebAssembly is a bit cumbersome at the moment, so feel free submit a PR or issue if you have feedback and/or improvements.
+
+## Basic unit tests
+
+These are unit tests that don't require any WIT files and are the easiest to work with. The [wasip2 example](../wasip2/) gives a demonstration for how to do this.
+
+## Guest-Host unit tests
+
+If tests require guest-host interactions via WIT, the required `//go:wasmexport` and `//go:wasmimport` functions needs to be present in the testfile. To get the [wasip2 example](../wasip2/) to compile, you'll need to append this codeblock to the end of the [handler_test.go file](../wasip2/export_wasi_http_incoming_handler/handler_test.go):
+
+```go
+//go:wasmexport wasi:http/incoming-handler@0.2.0#handle
+func wasm_export_wasi_http_incoming_handler_handle(arg0 int32, arg1 int32) {
+    Handle(wasi_http_types.IncomingRequestFromOwnHandle(int32(uintptr(arg0))), wasi_http_types.ResponseOutparamFromOwnHandle(int32(uintptr(arg1))))
+}
+```
+
+This codeblock is auto-generated in the [wit_exports.go file](../wasip2/wit_exports.go).
+
+Once the above codeblock is appended, run the following command to build the test component:
+
+```sh
+cd ../wasip2
+componentize-go --world wasip2-example componentize-tests --pkg ./export_wasi_http_incoming_handler
+```
+
+We haven't figured out the best way to run these, so stay tuned or feel free to try creating your own host implementation with wasmtime and see if you can find a way to get these to work!
+
+## Mixing Basic and Guest-Host unit tests
+
+It is not currently recommended to mix the two types of unit tests in the same package. componentize-go currently has no way of differentiating between the two.

examples/wasip2/Makefile

@@ -8,3 +8,10 @@ build-component: generate-bindings
 .PHONY: run
 run: build-component
 	wasmtime serve -Sp3,cli main.wasm
+
+# See the README in ../unit_tests for more information about using the `componentize-tests` subcommand
+build-tests: generate-bindings
+	componentize-go componentize-tests --wasip1 --pkg ./export_wasi_http_incoming_handler
+
+run-tests: build-tests
+	wasmtime run test_export_wasi_http_incoming_handler.wasm

examples/wasip2/README.md

@@ -13,4 +13,3 @@ make run
 # Invoke the application
 curl localhost:8080
 ```
-

examples/wasip2/export_wasi_http_incoming_handler/handler_test.go

@@ -0,0 +1,30 @@
+package export_wasi_http_incoming_handler
+
+import (
+	"testing"
+)
+
+func test_sum(a, b int) int {
+	return a + b
+}
+
+func TestSum(t *testing.T) {
+	tests := []struct {
+		name     string
+		a, b     int
+		expected int
+	}{
+		{"positive numbers", 2, 3, 5},
+		{"negative numbers", -1, -2, -3},
+		{"zeros", 0, 0, 0},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := test_sum(tt.a, tt.b)
+			if got != tt.expected {
+				t.Errorf("test_sum(%d, %d) = %d, expected %d", tt.a, tt.b, got, tt.expected)
+			}
+		})
+	}
+}

src/command.rs

@@ -1,5 +1,5 @@
 use crate::{bindings::generate_bindings, componentize};
-use anyhow::Result;
+use anyhow::{Result, anyhow};
 use clap::{Parser, Subcommand};
 use std::{ffi::OsString, path::PathBuf};
 
@@ -49,6 +49,9 @@ pub enum Command {
     /// Build a Go WebAssembly component.
     Componentize(Componentize),
 
+    /// Build Go test WebAssembly components.
+    ComponentizeTests(ComponentizeTests),
+
     /// Generate Go bindings for the world.
     Bindings(Bindings),
 }
@@ -68,6 +71,37 @@ pub struct Componentize {
     pub mod_path: Option<PathBuf>,
 }
 
+#[derive(Parser)]
+pub struct ComponentizeTests {
+    /// The path to the Go binary (or look for binary in PATH if `None`).
+    #[arg(long)]
+    pub go: Option<PathBuf>,
+
+    /// A package containing Go test files.
+    ///
+    /// This may be specified more than once, for example:
+    /// `--pkg ./cmd/foo --pkg ./cmd/bar`.
+    ///
+    /// The test components will be named using the last segment of the provided path, for example:
+    /// `--pkg ./foo/bar/baz` will result in a file named `test_bar_baz.wasm`
+    #[arg(long)]
+    pub pkg: Vec<PathBuf>,
+
+    /// Output directory for test components (or current directory if `None`).
+    ///
+    /// This will be created if it does not already exist.
+    #[arg(long, short = 'o')]
+    pub output: Option<PathBuf>,
+
+    /// Compiles the tests to a wasip1 component.
+    ///
+    /// This is helpful for unit tests that aren't interacting with the host.
+    /// Note: componentize-go has no way to differentiate between wasip1 and wasip2+ tests,
+    /// so it is recommended to keep the tests in separate packages.
+    #[arg(long)]
+    pub wasip1: bool,
+}
+
 #[derive(Parser)]
 pub struct Bindings {
     /// Output directory for bindings (or current directory if `None`).
@@ -95,28 +129,61 @@ pub fn run<T: Into<OsString> + Clone, I: IntoIterator<Item = T>>(args: I) -> Res
     match options.command {
         Command::Componentize(opts) => componentize(options.common, opts),
         Command::Bindings(opts) => bindings(options.common, opts),
+        Command::ComponentizeTests(opts) => componentize_tests(options.common, opts),
     }
 }
 
 fn componentize(common: Common, componentize: Componentize) -> Result<()> {
-    // Step 1: Build a WebAssembly core module using Go.
-    let core_module = componentize::build_wasm_core_module(
-        componentize.mod_path,
-        componentize.output,
-        componentize.go,
+    // Step 1: Build a wasip1 component using `go build`.
+    let p1_component = componentize::build_wasm_p1_component(
+        componentize.mod_path.as_ref(),
+        componentize.output.as_ref(),
+        componentize.go.as_ref(),
     )?;
 
-    // Step 2: Embed the WIT documents in the core module.
+    // Step 2: Embed the WIT documents in the wasip1 component.
     componentize::embed_wit(
-        &core_module,
+        &p1_component,
         &common.wit_path,
         common.world.as_deref(),
         &common.features,
         common.all_features,
     )?;
 
-    // Step 3: Update the core module to use the component model ABI.
-    componentize::core_module_to_component(&core_module)?;
+    // Step 3: Update the wasip1 component to use the current component model ABI.
+    componentize::p1_to_current(&p1_component)?;
+    Ok(())
+}
+
+fn componentize_tests(common: Common, componentize_tests: ComponentizeTests) -> Result<()> {
+    if componentize_tests.pkg.is_empty() {
+        return Err(anyhow!("Path to a package containing Go tests is required"));
+    }
+
+    for pkg in componentize_tests.pkg.iter() {
+        // Step 1: Build a wasip1 component using `go test -c`.
+        let p1_component = componentize::build_test_wasm_p1_component(
+            pkg,
+            componentize_tests.output.as_ref(),
+            componentize_tests.go.as_ref(),
+            componentize_tests.wasip1,
+        )?;
+
+        if !componentize_tests.wasip1 {
+            // Step 2: Embed the WIT documents in the wasip1 component.
+            componentize::embed_wit(
+                &p1_component,
+                &common.wit_path,
+                common.world.as_deref(),
+                &common.features,
+                common.all_features,
+            )?;
+
+            // Step 3: Update the wasip1 component to use the current component model ABI.
+            componentize::p1_to_current(&p1_component)?;
+        }
+    }
+
     Ok(())
 }
 

src/componentize.rs

@@ -1,6 +1,9 @@
 use crate::common::{make_path_absolute, parse_wit};
 use anyhow::{Context, Result, anyhow};
-use std::{path::PathBuf, process::Command};
+use std::{
+    path::{Path, PathBuf},
+    process::Command,
+};
 
 /// Ensure that the Go version is compatible with the embedded Wasm tooling.
 fn check_go_version(go_path: &PathBuf) -> Result<()> {
@@ -43,8 +46,8 @@ fn check_go_version(go_path: &PathBuf) -> Result<()> {
     }
 }
 
-/// Update the WebAssembly core module to use the component model ABI.
-pub fn core_module_to_component(wasm_file: &PathBuf) -> Result<()> {
+/// Update the wasip1 component to use the current component model ABI.
+pub fn p1_to_current(wasm_file: &PathBuf) -> Result<()> {
     // In the rare case the snapshot needs to be updated, the latest version
     // can be found here: https://github.com/bytecodealliance/wasmtime/releases
     const WASIP1_SNAPSHOT: &[u8] = include_bytes!("wasi_snapshot_preview1.reactor.wasm");
@@ -84,11 +87,116 @@ pub fn embed_wit(
     Ok(())
 }
 
-/// Compiles a Go application to WebAssembly core.
-pub fn build_wasm_core_module(
-    go_module: Option<PathBuf>,
-    out: Option<PathBuf>,
-    go_path: Option<PathBuf>,
+pub fn build_test_wasm_p1_component(
+    path: &Path,
+    output_dir: Option<&PathBuf>,
+    go_path: Option<&PathBuf>,
+    use_wasip1_flags: bool,
+) -> Result<PathBuf> {
+    let go = match &go_path {
+        Some(p) => make_path_absolute(p)?,
+        None => PathBuf::from("go"),
+    };
+
+    check_go_version(&go)?;
+
+    let test_wasm_path = {
+        // The directory in which the test component will be placed
+        let test_dir = match output_dir {
+            Some(p) => make_path_absolute(p)?,
+            None => std::env::current_dir()?,
+        };
+
+        test_dir.join(get_test_filename(path))
+    };
+
+    // Ensuring the newly compiled wasm file overwrites any previously-existing wasm file
+    if test_wasm_path.exists() {
+        std::fs::remove_file(&test_wasm_path)?;
+    }
+
+    if let Some(dir) = output_dir {
+        std::fs::create_dir_all(dir)?;
+    }
+
+    // The -ldflags arg mutes the unit test output, so it is ommitted
+    let wasip1_args = [
+        "test",
+        "-c",
+        "-buildmode=c-shared",
+        "-o",
+        test_wasm_path
+            .to_str()
+            .expect("the combined paths of 'output-dir' and 'pkg' are not valid unicode"),
+        path.to_str().expect("pkg path is not valid unicode"),
+    ];
+
+    let wasip2_and_greater_args = [
+        "test",
+        "-c",
+        "-buildmode=c-shared",
+        "-ldflags=-checklinkname=0",
+        "-o",
+        test_wasm_path
+            .to_str()
+            .expect("the combined paths of 'output-dir' and 'pkg' are not valid unicode"),
+        path.to_str().expect("pkg path is not valid unicode"),
+    ];
+
+    let output = if use_wasip1_flags {
+        Command::new(&go)
+            .args(wasip1_args)
+            .env("GOOS", "wasip1")
+            .env("GOARCH", "wasm")
+            .output()?
+    } else {
+        Command::new(&go)
+            .args(wasip2_and_greater_args)
+            .env("GOOS", "wasip1")
+            .env("GOARCH", "wasm")
+            .output()?
+    };
+
+    if !output.status.success() {
+        return Err(anyhow!(
+            "'go test -c' command failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        ));
+    }
+
+    Ok(test_wasm_path)
+}
+
+/**
+ * `./foo/bar/baz` should be `test_bar_baz.wasm`
+ * `./foo/bar` should be `test_foo_bar.wasm`
+ * `./bar` should be `test_bar.wasm`
+ * `/usr/bin/foo/bar/baz` should be `test_bar_baz.wasm`
+*/
+fn get_test_filename(path: &Path) -> String {
+    let components: Vec<&str> = path
+        .components()
+        .filter_map(|c| match c {
+            // Filter out the `/` and `.`
+            std::path::Component::Normal(s) => s.to_str(),
+            _ => None,
+        })
+        .collect();
+
+    let tail = if components.len() >= 2 {
+        &components[components.len() - 2..]
+    } else {
+        &components[..]
+    };
+
+    format!("test_{}.wasm", tail.join("_"))
+}
+
+/// Compiles a Go application to a wasip1 component.
+pub fn build_wasm_p1_component(
+    go_module: Option<&PathBuf>,
+    out: Option<&PathBuf>,
+    go_path: Option<&PathBuf>,
 ) -> Result<PathBuf> {
     let go = match &go_path {
         Some(p) => make_path_absolute(p)?,
@@ -102,8 +210,7 @@ pub fn build_wasm_core_module(
         None => std::env::current_dir()?.join("main.wasm"),
     };
 
-    // The `go build` command doesn't overwrite the output file, which causes
-    // issues if the `componentize-go componentize` command is run multiple times.
+    // Ensuring the newly compiled wasm file overwrites any previously-existing wasm file
     if out_path_buf.exists() {
         std::fs::remove_file(&out_path_buf)?;
     }