Introduction

A minimal golden file testing library for Rust, when golden files are required for external api requests.

Warning & Disclaimer

Currently intended for personal use, and does not respect semver for v0.1.

Documentation

For detailed documentation, check docs.rs

lib.rs:

Introduction

A minimal golden file testing library for Rust, when golden files are required for external api requests.

Warning & Disclaimer

Currently intended for personal use, and has the following limitations:

• The API is not stable.
• The library could be appropriate only for specific use cases.

When to use

This crate is intended to be used in the situation below:

• You're sending external api requests in your library/binary.
• You want to mock the responses for testing purposes.
• You want to create the mocks based on the actual responses.
  • As so, you want to make actual api requests,
  • then save these to golden files mocking.

The logic above ensures that your mocks are based on actual external api responses but also allows testing

1. in constrained environments when you can't make actual external requests,
2. when the external api server is unavailable.

Testing logic

In the case which fits the When to use section, you can use the following logic:

1. Create a mock server which intercepts requests:
   • Your function, which sends external api requests, should accept a domain parameter, so it can be injected as a dependency. You can set this domain as:
     • In production: The actual domain
     • In tests: The mock server uri
2. Serve the mock response:
   • When a golden file does not exist (or an update is required via the GOLDRUST_UPDATE_GOLDEN_FILES env var):
     1. Create an external api request
     2. Save the response body to the golden file
   • When a golden file exists and no update is required, serve the golden file for mock responses

Async

Only supports async, as was intended to be used in relevance to http request mocking.

Usage

Check tests/base.rs for a full example. Instead of giving a detailed implementation on how tests should be set, this library provides a ResponseSource enum for the library user to use.

Requirements

Related environment variables should be set:

• GOLDRUST_DIR: String
  • The directory where the golden files will be saved.
  • Defaults to tests/golden.
• GOLDRUST_ALLOW_EXTERNAL_API_CALL: bool
  • Whether external api calls are allowed.
  • Defaults to false.
• GOLDRUST_UPDATE_GOLDEN_FILES: bool
  • Whether golden files should be updated.
  • Defaults to false.

Some combinations are invariant and will panic: (for example, you can't update golden files without allowing external api calls).

Current Limitations

• Content that is to be created as golden files should be JSON serializable, deserializable. (This is because the golden files are saved as JSON files)
• Assumes that only a single golden file is required per test. (The current implementation creates golden file names based on the thread name of the test) If multiple golden files are required, it is recommended to break down the test in the current implementation. (Having to pass down the golden file name and track each seemed like an unnecessary complexity for now)