darkroom 0.5.0

A contract testing tool built in Rust
Documentation

Darkroom

Crates.io Docs.rs

A contract testing tool built in Rust using the filmReel format.

Usage:

dark:

Usage: dark [<address>] [-v] [--tls] [-p <proto>] [-H <header>] [-C <cut-out>] [-i] <command> [<args>]

Darkroom: A contract testing tool built in Rust using the filmReel format.

Options:
  -v, --verbose     enable verbose output
  --tls             enable TLS (automatically inferred for HTTP/S)
  -p, --proto       pass proto files used for payload forming
  -H, --header      fallback header passed to the specified protocol
  -C, --cut-out     output of final cut file
  -i, --interactive interactive frame sequence transitions
  --help            display usage information

Commands:
  version           Returns CARGO_PKG_VERSION
  take              Takes a single frame, emitting the request then validating
                    the returned response
  record            Attempts to play through an entire Reel sequence running a
                    take for every frame in the sequence

dark take:

Usage: dark take <frame> -c <cut> [-o <take-out>]

Takes a single frame, emitting the request then validating the returned response

Options:
  -c, --cut         filepath of input cut file
  -o, --take-out    output of take file
  --help            display usage information

dark record:

Usage: dark record <reel_path> <reel_name> [<merge_cuts...>] [-c <cut>] [-b <component>] [-o <take-out>] [-r <range>] [-t <timeout>] [-s]

Attempts to play through an entire Reel sequence running a take for every frame in the sequence

Options:
  -c, --cut         filepath of input cut file
  -b, --component   repeatable component reel pattern using an ampersand
                    separator: --component "<dir>&<reel_name>"
  -o, --take-out    output directory for successful takes
  -r, --range       the range (inclusive) of frames that a record session will
                    use, colon separated: --range <start>:<end> --range <start>:
  -t, --timeout     client request timeout in seconds, --timeout 0 disables
                    request timeout [default: 30]
  -s, --timestamp   print timestamp at take start, error return, and reel
                    completion
  --help            display usage information

Examples:

SOPS example:

# destructively merge FIFO sops "KEY_NAME" value into the in-memory cut register
dark record ./reel_path reel_name --cut ./reel_name.cut.json \
    <(sops -d --extract '["KEY_NAME"]' path/to/myfile.enc.json)

# multiple merge cuts can be used, with values being overridden left to right (right will have newer values)
dark -v --interactive record ./test_data post --cut ./test_data/post.cut.json \
    <(echo '{"new":"value"}') <(echo '{"newer": "value", "new":"overridden"}')

Cut output example:

# echo the origin "${IP}" that gets written to the cut register from the httpbin.org POST request
dark --cut-out >(jq .IP) take ./test_data/post.01s.body.fr.json --cut ./test_data/post.cut.json

Changes:

0.2:

  • HTTP support
  • added form key to HTTP frame requests: {"request":{"uri":"POST post","form":{"key":"val","array[0]":"val0"}}}
  • full JSON object storage and retrieval, the cut register is no longer a flat associative array, strings are still used to map to JSON objects for templating
  • variable discarding: ${lowercase} variables will only be kept around for the duration of the frame
  • headers and entrypoints can be stored and read on a per JSON frame basis
  • SOPS/JSON secrets support

0.2.1:

  • added hidden variable support, hidden variables are defined with a leading underscore: ${_HIDDEN}
  • added dark version command
  • moved common parameters into the main dark command to be shared across subcommands

0.2.3:

  • added component reel support, component reels are generated as a prelude to the provided reel dark record --component "<dir>&<reel_name>" ./dir/ my_reel_name
  • added anyhow error handling
  • --cut-out can now be returned on a failed record or take

0.3.0:

  • removed YAML deserialization now that grpcurl properly emits JSON errors
  • added retry attempts to frame requests: {"request":{"attempts": {"times": 5, "ms": 500}}}

0.3.1:

  • frame response body is now optional

0.3.2:

  • request retry attempts now include a process_response comparison
  • ToTakeHiddenColouredJson is now a generic trait
  • ToStringHidden is now a generc trait
  • moved styler out of take.rs and into lib.rs

0.3.3:

  • range is added to recordings: dark record --range "<start_u32>:<end_u32>" ./dir/ my_reel_name
  • grpcurl errors propagate to stdout properly
  • "request"["form"] request building URL functionality moved to "request"["query"]
  • "request"["form"] now properly bulids the form data of the HTTP request

0.4.0:

  • range is added to recordings: dark record --range "<start_u32>:<end_u32>" ./dir/ my_reel_name

0.5.0:

  • timestamps are added to recordings: dark record record ./test_data post --timestamp
  • 30 sec default timeout can now be overridden: dark record record ./test_data post --timeout 2
  • reel sequence numbers are now checked for duplicates