{"id":13693271,"url":"https://github.com/fastly/Viceroy","last_synced_at":"2025-05-02T21:31:49.113Z","repository":{"id":37079374,"uuid":"384249813","full_name":"fastly/Viceroy","owner":"fastly","description":"Viceroy provides local testing for developers working with Compute.","archived":false,"fork":false,"pushed_at":"2025-04-30T14:51:50.000Z","size":3014,"stargazers_count":149,"open_issues_count":61,"forks_count":38,"subscribers_count":35,"default_branch":"main","last_synced_at":"2025-04-30T15:33:44.003Z","etag":null,"topics":["fastly-featured","fastly-product","tool"],"latest_commit_sha":null,"homepage":"https://fastly.dev/learning/compute/testing/#running-a-local-testing-server","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastly.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-08T21:14:41.000Z","updated_at":"2025-04-26T01:39:45.000Z","dependencies_parsed_at":"2023-12-01T20:29:06.009Z","dependency_job_id":"30492e52-1180-4627-b578-6cbfb4bbc5af","html_url":"https://github.com/fastly/Viceroy","commit_stats":{"total_commits":366,"total_committers":32,"mean_commits":11.4375,"dds":0.7978142076502732,"last_synced_commit":"a38ed29cf69e7559903e0114b19b6ce446cae97c"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastly%2FViceroy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastly%2FViceroy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastly%2FViceroy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastly%2FViceroy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastly","download_url":"https://codeload.github.com/fastly/Viceroy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251732759,"owners_count":21634831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastly-featured","fastly-product","tool"],"created_at":"2024-08-02T17:01:07.833Z","updated_at":"2025-05-02T21:31:48.357Z","avatar_url":"https://github.com/fastly.png","language":"Rust","funding_links":[],"categories":["工具(库)"],"sub_categories":["其他"],"readme":"# Viceroy\n\nViceroy provides local testing for developers working with Fastly Compute. It\nallows you to run services written against the Compute APIs on your local\ndevelopment machine, and allows you to configure testing backends for your\nservice to communicate with.\n\nViceroy is normally used through the [Fastly CLI's `fastly compute serve`\ncommand][cli], where it is fully integrated into Compute workflows.\nHowever, it is also a standalone open source tool with its own CLI and a\nRust library that can be embedded into your own testing infrastructure.\n\n[cli]: https://developer.fastly.com/learning/compute/testing/#running-a-local-testing-server\n\n## Installation\n\n### Via the Fastly CLI\n\nAs mentioned above, most users of Compute should do local testing via the\nFastly CLI, rather than working with Viceroy directly. Any [CLI release] of\nversion 0.34 or above supports local testing, and the workflow is documented\n[here][cli].\n\n[CLI release]: https://github.com/fastly/cli/releases\n\n### As a standalone tool from crates.io\n\nTo install Viceroy as a standalone tool, you'll need to first\n[install Rust](https://www.rust-lang.org/tools/install) if you haven't already.\nThen run `cargo install viceroy`, which will download and build the latest\nViceroy release.\n\n## Usage as a library\n\nViceroy can be used as a [Rust library](https://docs.rs/viceroy-lib/). This is useful if you want to run integration tests in the same codebase. We provide a helper method [`handle_request`](https://docs.rs/viceroy-lib/0.2.6/viceroy_lib/struct.ExecuteCtx.html#method.handle_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 build [cache](https://github.com/actions/cache/blob/main/examples.md#rust---cargo) for Rust. This will speed up your build times a lot.\n\n## Usage as a standalone tool\n\n**NOTE**: the Viceroy standalone CLI has a somewhat different interface from that\nof [the Fastly CLI][cli]. Command-line options below describe the standalone\nViceroy interface.\n\nAfter installation, the `viceroy` command should be available on your path. The\nonly required argument is the path to a compiled `.wasm` blob, which can be\nbuilt by `fastly compute build`. The Fastly CLI should put the blob at\n`bin/main.wasm`. To test the service, you can run:\n\n```\nviceroy bin/main.wasm\n```\n\nThis will start a local server (by default at: `http://127.0.0.1:7676`), which can\nbe used to make requests to your Compute service locally. You can make requests\nby using [curl](https://curl.se/), or you can send a simple GET request by visiting\nthe URL in your web browser.\n\n## Usage as a test runner\nViceroy can also be used as a test runner for running Rust unit tests for Compute applications in the following way:\n\n1. Ensure the `viceroy` command is available in your path\n2. Add the following to your project's `.cargo/config`:\n```\n[build]\ntarget = \"wasm32-wasi\"\n\n[target.wasm32-wasi]\nrunner = \"viceroy run -C fastly.toml -- \"\n```\n3. Install [cargo-nextest](https://nexte.st/book/installation.html)\n4. Write your tests that use the fastly crate. For example:\n```Rust\n#[test]\nfn test_using_client_request() {\n    let client_req = fastly::Request::from_client();\n    assert_eq!(client_req.get_method(), Method::GET);\n    assert_eq!(client_req.get_path(), \"/\");\n}\n\n#[test]\nfn test_using_bodies() {\n    let mut body1 = fastly::Body::new();\n    body1.write_str(\"hello, \");\n    let mut body2 = fastly::Body::new();\n    body2.write_str(\"Viceroy!\");\n    body1.append(body2);\n    let appended_str = body1.into_string();\n    assert_eq!(appended_str, \"hello, Viceroy!\");\n}\n\n#[test]\nfn test_a_handler_with_fastly_types() {\n    let req = fastly::Request::get(\"http://example.com/Viceroy\");\n    let resp = some_handler(req).expect(\"request succeeds\");\n    assert_eq!(resp.get_content_type(), Some(TEXT_PLAIN_UTF_8));\n    assert_eq!(resp.into_body_str(), \"hello, /Viceroy!\");\n}\n```\n5. Run your tests with `cargo nextest run`:\n```\n % cargo nextest run\n   Compiling unit-tests-test v0.1.0\n    Finished test [unoptimized + debuginfo] target(s) in 1.16s\n    Starting 3 tests across 1 binaries\n        PASS [   2.106s] unit-tests-test::bin/unit-tests-test tests::test_a_handler_with_fastly_types\n        PASS [   2.225s] unit-tests-test::bin/unit-tests-test tests::test_using_bodies\n        PASS [   2.223s] unit-tests-test::bin/unit-tests-test tests::test_using_client_request\n------------\n     Summary [   2.230s] 3 tests run: 3 passed, 0 skipped\n```\n\nThe reason that `cargo-nextest` is needed rather than just `cargo 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-nextest [handles that orchestration for us](https://nexte.st/book/how-it-works.html#the-nextest-model).\n\n## Documentation\n\nSince the Fastly CLI uses Viceroy under the hood, the two share documentation for\neverything other than CLI differences. You can find general documentation for\nlocal testing [here][cli], and documentation about configuring local testing\n[here][toml-docs]. Documentation for Viceroy's CLI can be found via `--help`.\n\n[toml-docs]: https://developer.fastly.com/reference/fastly-toml/#local-server\n\n## Colophon\n\n![Viceroy](doc/logo.png)\n\nThe viceroy is a butterfly whose color and pattern mimics that of the monarch\nbutterfly but is smaller in size.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastly%2FViceroy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastly%2FViceroy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastly%2FViceroy/lists"}