Repository files navigation

Viceroy provides local testing for developers working with Fastly Compute. Itallows you to run services written against the Compute APIs on your localdevelopment machine, and allows you to configure testing backends for yourservice to communicate with.

Viceroy is normally used through theFastly CLI'sfastly compute servecommand, where it is fully integrated into Compute workflows.However, it is also a standalone open source tool with its own CLI and aRust library that can be embedded into your own testing infrastructure.

As mentioned above, most users of Compute should do local testing via theFastly CLI, rather than working with Viceroy directly. AnyCLI release ofversion 0.34 or above supports local testing, and the workflow is documentedhere.

To install Viceroy as a standalone tool, you'll need to firstinstall Rust if you haven't already.Then runcargo install viceroy, which will download and build the latestViceroy release.

Viceroy can be used as aRust library. This is useful if you want to run integration tests in the same codebase. We provide a helper methodhandle_request. Before you build or test your code, we recommend to set the release flag e.g.cargo test --release otherwise, the execution will be very slow. This has to do with the Cranelift compiler, which is extremely slow when compiled in debug mode. Besides that, if you use Github Actions don't forget to setup a buildcache for Rust. This will speed up your build times a lot.

NOTE: the Viceroy standalone CLI has a somewhat different interface from thatofthe Fastly CLI. Command-line options below describe the standaloneViceroy interface.

After installation, theviceroy command should be available on your path. Theonly required argument is the path to a compiled.wasm blob, which can bebuilt byfastly compute build. The Fastly CLI should put the blob atbin/main.wasm. To test the service, you can run:

viceroy bin/main.wasm

This will start a local server (by default at:http://127.0.0.1:7676), which canbe used to make requests to your Compute service locally. You can make requestsby usingcurl, or you can send a simple GET request by visitingthe URL in your web browser.

Viceroy can also be used as a test runner for running Rust unit tests for Compute applications in the following way:

1. Ensure theviceroy command is available in your path
2. Add the following to your project's.cargo/config:

[build]target = "wasm32-wasi"[target.wasm32-wasi]runner = "viceroy run -C fastly.toml -- "

3. Installcargo-nextest
4. Write your tests that use the fastly crate. For example:

#[test]fntest_using_client_request(){let client_req = fastly::Request::from_client();assert_eq!(client_req.get_method(),Method::GET);assert_eq!(client_req.get_path(),"/");}#[test]fntest_using_bodies(){letmut body1 = fastly::Body::new();    body1.write_str("hello, ");letmut body2 = fastly::Body::new();    body2.write_str("Viceroy!");    body1.append(body2);let appended_str = body1.into_string();assert_eq!(appended_str,"hello, Viceroy!");}#[test]fntest_a_handler_with_fastly_types(){let req = fastly::Request::get("http://example.com/Viceroy");let resp =some_handler(req).expect("request succeeds");assert_eq!(resp.get_content_type(),Some(TEXT_PLAIN_UTF_8));assert_eq!(resp.into_body_str(),"hello, /Viceroy!");}

5. Run your tests withcargo nextest run:

 % cargo nextest run   Compiling unit-tests-test v0.1.0    Finished test [unoptimized + debuginfo] target(s) in 1.16s    Starting 3 tests across 1 binaries        PASS [   2.106s] unit-tests-test::bin/unit-tests-test tests::test_a_handler_with_fastly_types        PASS [   2.225s] unit-tests-test::bin/unit-tests-test tests::test_using_bodies        PASS [   2.223s] unit-tests-test::bin/unit-tests-test tests::test_using_client_request------------     Summary [   2.230s] 3 tests run: 3 passed, 0 skipped

The reason thatcargo-nextest is needed rather than justcargo test is to allow tests to keep executing if any other test fails. There is no way to recover from a panic in wasm, so test execution would halt as soon as the first test failure occurs. Because of this, we need each test to be executed in its own wasm instance and have the results aggregated to report overall success/failure. cargo-nextesthandles that orchestration for us.

Since the Fastly CLI uses Viceroy under the hood, the two share documentation foreverything other than CLI differences. You can find general documentation forlocal testinghere, and documentation about configuring local testinghere. Documentation for Viceroy's CLI can be found via--help.

The viceroy is a butterfly whose color and pattern mimics that of the monarchbutterfly but is smaller in size.