touca-wrench 0.1.2
Utility CLI for managing Touca archive files
License: Apache-2.0
Requires Python: >=3.6
Keywords: touca,snapshot testing,regression testing

# Touca Utility CLI

[![PyPI](https://img.shields.io/pypi/v/touca-wrench)](https://pypi.org/project/touca-wrench/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/touca-wrench)](https://pypi.org/project/touca-wrench/)
[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/trytouca/touca-wrench/touca-wrench-main)](https://github.com/trytouca/touca-wrench/actions/workflows/main.yml?query=branch%3Amain+event%3Apush)
[![PyPI - License](https://img.shields.io/pypi/l/touca-wrench)](https://github.com/trytouca/touca-wrench/blob/main/LICENSE)

Touca helps you understand the true impact of your day to day code changes
on the behavior and performance of your overall software, as you write code.

Touca SDKs let you describe the behavior and performance of your code by
capturing values of interesting variables and runtime of important functions.
We remotely compare your description against a trusted version of your
software, visualize all differences, and report them in near real-time.
Learn more at [docs.touca.io](https://docs.touca.io).

Touca Utility CLI helps you manage Touca archive files. It is used by Touca enterprise customers who choose to keep a local copy of their test results
when running Touca tests on a dedicated test server.

## Install

Touca Utility CLI can be installed via [pip](https://pypi.org/project/touca-wrench>):

```bash
pip install touca-wrench
```

We formally support Python v3.6 and newer on Windows, Linux and macOS platforms.

## Operations

### Compressing Archive Files

Touca archive files are stored in binary format. You can still compress them
for optimum storage.

```bash
wrench zip --src=./raw/acme/suite --out=./zipped/acme/suite
```

### Extracting Archive Files

You can extract compressed archive files by running using the `unzip` operation.

```bash
wrench unzip --src=./zipped/acme/suite --out=./unzipped/acme/suite
```

### Merging Archive Files

By default, Touca test framework generates one binary file for each test case
as it is executed. For convenience, you can use the `merge` operation to merge these binary files into one or more archive files of up to 10MB in size.

```bash
wrench merge --src=./unzipped/acme/suite --out=./merged/acme/suite --cli=./path/to/touca_cli --logdir=./logs
```

Where `touca_cli` is the low-level utility executable that is shipped with the Touca SDK for C++.

### Posting Archive Files

This operation is useful when back-filling a new instance of Touca server with binary test results from previous versions of your workflows.

```bash
wrench post --src=./merged/acme/suite --api-key <your-api-key> --api-url <your-api-url>
```

This command scans the archive directory for sub-directories that contain
the test results generated for a given version of your Touca test and
submits them one-by-one to the Touca server.

> Note: `post` operation expects the `merge` operation to have been run. It
> ignores subdirectories that do not end with `-merged` suffix.

### Updating Metadata

By design, Touca archive files include the metadata for each test case including
the slugs for `team`, `suite` and `revision`. You can use the `update` operation
to modify the metadata fields to submit test results that were originally created
for one suite to a different suite.

```bash
wrench update --src ./merged/acme/unknown --out ./updated/acme/unknown --cli ./path/to/touca_cli --logdir ./logs --team acme-2 --suite suite-2 --revision 2.0
```

Where `touca_cli` is the low-level utility executable that is shipped with the Touca SDK for C++.

## License

This repository is released under the Apache-2.0 License. See
[LICENSE](https://github.com/trytouca/touca-wrench/blob/main/LICENSE).