README
¶
xtp-test
A Go test framework for xtp / Extism plugins.
Example
package main
import (
"encoding/json"
"fmt"
xtptest "github.com/dylibso/xtp-test-go"
)
// You _must_ export a single `test` function in order for the test runner to call something
//
//go:export test
func test() int32 {
// call the tested plugin's "count_vowels" function, passing it some data
output := xtptest.CallString("count_vowels", []byte("hello"))
// check that the output is as expected
xtptest.AssertNe("we got some output", output, "")
// create a named group of tests. NOTE: plugin state is reset before and after the group runs.
xtptest.Group("check how fast the function performs", func() {
// check the amount of time in seconds or nanoseconds spent in the plugin function.
sec := xtptest.TimeSeconds("count_vowels", []byte("hello"))
xtptest.AssertLt("it should be fast", sec, 0.1)
ns := xtptest.TimeNanos("count_vowels", []byte("hello"))
xtptest.AssertLt("it should be really fast", ns, 300000)
})
xtptest.Group("check that count_vowels maintains state", func() {
accumTotal := 0
for i := 0; i < 10; i++ {
c := fromJson(xtptest.CallBytes("count_vowels", []byte("this is a test")))
accumTotal += c.Count
xtptest.AssertEq(fmt.Sprintf("total should be incremented to: %d", accumTotal), c.Total, accumTotal)
}
})
// as this is an Extism plugin, return a status/error code
return 0
}
func fromJson(data []byte) CountVowels {
var res CountVowels
_ = json.Unmarshal(data, &res)
return res
}
type CountVowels struct {
Vowels string `json:"vowels"`
Total int `json:"total"`
Count int `json:"count"`
}
func main() {}
API Docs
Please see the godoc
documentation page for full details.
Usage
1. Create a Go project using the XTP Test package
mkdir plugintest && cd plugintest
go mod init <your module>
go get github.com/dylibso/xtp-test-go
2. Write your test in Go
// test.go
package main
import (
"encoding/json"
"fmt"
xtptest "github.com/dylibso/xtp-test-go"
)
//go:export test
func test() int32 {
// call the tested plugin's "count_vowels" function, passing it some data
output := xtptest.CallString("count_vowels", []byte("hello"))
// check that the output is as expected
xtptest.AssertNe("we got some output", output, "")
// ...
3. Compile your test to .wasm:
Ensure you have
tinygo installed. Eventually
you can use the go compiler, but the test runner must find an exported
test function from the test plugin, and go cannot currently export any
function other than _start.
tinygo build -o test.wasm -target wasi test.go
4. Run the test against your plugin: Once you have your test code as a
.wasm module, you can run the test against your plugin using the xtp CLI:
Install xtp
curl https://static.dylibso.com/cli/install.sh | sudo sh
Run the test suite
xtp plugin test ./plugin-*.wasm --with test.wasm --mock-host host.wasm
# ^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^^^
# your plugin(s) test to run optional mock host functions
Note: The optional mock host functions must be implemented as Extism plugins, whose exported functions match the host function signature imported by the plugins being tested.
Need Help?
Please reach out via the
#xtp channel on Discord.
Documentation
¶
Index ¶
- func Assert(msg string, outcome bool, reason string)
- func AssertEq(msg string, x any, y any)
- func AssertGt[T cmp.Ordered](msg string, x T, y T)
- func AssertGte[T cmp.Ordered](msg string, x T, y T)
- func AssertLt[T cmp.Ordered](msg string, x T, y T)
- func AssertLte[T cmp.Ordered](msg string, x T, y T)
- func AssertNe(msg string, x any, y any)
- func Call(funcName string, input []byte) pdk.Memory
- func CallBytes(funcName string, input []byte) []byte
- func CallString(funcName string, input []byte) string
- func Group(name string, tests func())
- func MockInput() pdk.Memory
- func MockInputBytes() []byte
- func MockInputString() string
- func Reset()
- func TimeNanos(funcName string, input []byte) uint64
- func TimeSeconds(funcName string, input []byte) float64
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Assert ¶
Assert that the `outcome` is true, naming the assertion with `msg`, which will be used as a label in the CLI runner.
func AssertEq ¶
Assert that `x` and `y` are equal, naming the assertion with `msg`, which will be used as a label in the CLI runner.
func AssertGt ¶
Assert that `x` is greater than `y`, naming the assertion with `msg`, which will be used as a label in the CLI runner.
func AssertGte ¶
Assert that `x` is greater than or equal to `y`, naming the assertion with `msg`, which will be used as a label in the CLI runner.
func AssertLt ¶
Assert that `x` is less than `y`, naming the assertion with `msg`, which will be used as a label in the CLI runner.
func AssertLte ¶
Assert that `x` is less than or equal to `y`, naming the assertion with `msg`, which will be used as a label in the CLI runner.
func AssertNe ¶
Assert that `x` and `y` are not equal, naming the assertion with `msg`, which will be used as a label in the CLI runner.
func Call ¶
Call a function from the Extism plugin being tested, passing input and returning its output Memory.
func CallBytes ¶
Call a function from the Extism plugin being tested, passing input and returning its output as []byte.
func CallString ¶
Call a function from the Extism plugin being tested, passing input and returning its output as a string.
func Group ¶
func Group(name string, tests func())
Run a test group, resetting the plugin before and after the group is run.
func MockInput ¶ added in v0.0.2
func MockInput() pdk.Memory
Read the mock test input provided by the test runner, returns a Memory object. This input is defined in an xtp.toml file, or by the --mock-input-data or --mock-input-file flags.
func MockInputBytes ¶ added in v0.0.2
func MockInputBytes() []byte
Read the mock test input provided by the test runner, returns the input as []byte. This input is defined in an xtp.toml file, or by the --mock-input-data or --mock-input-file flags.
func MockInputString ¶ added in v0.0.2
func MockInputString() string
Read the mock test input provided by the test runner, returns the input as a string. This input is defined in an xtp.toml file, or by the --mock-input-data or --mock-input-file flags.
func TimeNanos ¶
Call a function from the Extism plugin being tested, passing input and returning the time in nanoseconds spent in the fuction.
func TimeSeconds ¶
Call a function from the Extism plugin being tested, passing input and returning the time in seconds spent in the fuction.
Types ¶
This section is empty.
Source Files
Directories