Skip to main content

Managing Local Files

Touca result files are generated in binary format. Each file may contain test results captured for any number of test cases. Typical Touca test tools do not need to generate test result files since their output is directly sent to the Touca server in real-time as tests are executed. But some organizations may choose to store test results on filesystem for reproducibility. touca results command helps you manage these local files.

touca help results
usage: touca results [-h] {list,merge,post,compress,extract,remove,edit} ...

Manage local test results

positional arguments:
    ls                  list local touca archive files
    merge               merge local touca archive files
    post                submit binary archives to a Touca server
    compress            Compress touca archive files
    extract             extract compressed binary archives
    remove              remove local touca archive files
    edit                Edit metadata of touca archive files

Listing archives​

touca help results ls
usage: touca results ls [--src-dir SRC_DIR] [--filter FILTER]

list local touca archive files

options:
  --src-dir SRC_DIR  Path to test results directory. Defaults to ~/.touca/results.
  --filter FILTER    Limit results to a given suite or version. Value should be in form of suite[/version].

You can use touca results ls to list all local archives in the default Touca results directory ~/.touca/results. You can use --src-dir to change the results directory and --filter=example[/v1.0] to limit the results to a given suite or version.

$ touca results ls
🗃
└── students
    ├── v5.1
    │   └── 3 binary files
    ├── v5.2
    │   └── 3 binary files
    └── v5.3
        └── 3 binary files

Merging archives​

touca help results merge
usage: touca results merge [src_dir] [out_dir]

Merge local touca archive files

positional arguments:
  src_dir  Directory with with binary files. Defaults to ~/.touca/results.
  out_dir  Directory with merged files. Defaults to ~/.touca/merged.

Touca test framework generate separate binary archives for each test case as they are executed. You can use touca results merge to merge binary files of the same suite into one or more archive files of up to 10MB in size.

students ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00

By default, the test results found in ~/.touca/results will be merged into ~/.touca/merged. You can pass arguments src_dir to change this directory. You can also pass an extra argument out_dir to change the directory where the merged archives are generated.

Posting archives​

touca help results post
usage: touca results post [--api-key API_KEY] [--api-url API_URL] [--dry-run] [src_dir]

submit binary archives to a Touca server

positional arguments:
  src_dir            Directory with binary files. defaults to ~/.touca/results

Credentials:
  Server API Key and URL. Not required when specified in the active configuration profile. Ignored when "--dry-run" is specified.

  --api-key API_KEY  Touca API Key
  --api-url API_URL  Touca API URL

Other:
  --dry-run          Check what your command would do when run without this option

You can use touca results post to scan a given directory for local test results and submit them one-by-one, sorted by their version value, to the Touca server.

$ touca config set api-key=a66fe9d2-00b7-4f7c-95d9-e1b950d0c906
$ touca config set team=tutorial-509512
$ touca post

students/v5.1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
students/v5.2 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
students/v5.3 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00

By default, the test results found in ~/.touca/results are posted. You can pass arguments src_dir to change this directory.

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

Compressing archives​

touca help results compress
usage: touca results compress [src_dir] [out_dir]

Compress touca archive files

positional arguments:
  src_dir  Path to test results directory. Defaults to ~/.touca/results.
  out_dir  Directory to store compressed files. Defaults to ~/.touca/zip

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

touca compress

students/v5.1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
students/v5.2 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
students/v5.3 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00

By default, the test results found in ~/.touca/results are compressed into separate files for each version into ~/.touca/zip. You can pass arguments src_dir to change this directory. You can also pass an extra argument out_dir to change where the compressed files are generated.

Extracting archives​

touca help results extract
usage: touca results extract [src_dir] [out_dir]

Extract compressed binary archives

positional arguments:
  src_dir  Directory with compressed files. Defaults to ~/.touca/zip.
  out_dir  Directory to extract binary files into. Defaults to ~/.touca/results

You can extract compressed archives via touca results extract:

touca extract

students ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00

By default, the test results found in ~/.touca/zip are extracted into into ~/.touca/results. You can pass arguments src_dir to change this directory. You can also pass an extra argument out_dir to change where the extracted files are generated.

Removing archives​

touca help results rm
usage: touca results rm [--src-dir SRC_DIR] [--filter FILTER] [--dry-run]

Remove local touca archive files

options:
  --src-dir SRC_DIR  Path to test results directory. Defaults to ~/.touca/results.
  --filter FILTER    Limit results to a given suite or version. Value should be in form of suite[/version].
  --dry-run          Check what your command would do when run without this option

You can also use touca results rm to remove local archives from the default Touca results directory. In addition to --src-dir and --filter, touca results rm supports --dry-run to help you double check which binary archives will be removed, without removing them.

$ touca results rm

students_test/6.1 ━━━━━━━━━━━━━━━━ 100% 0:00:00
students_test/6.0 ━━━━━━━━━━━━━━━━ 100% 0:00:00

Editing archives​

touca help results edit
usage: touca results edit [--filter FILTER] [--team TEAM] [--suite SUITE] [--version VERSION] [src_dir] [out_dir]

Edit metadata of touca archive files

positional arguments:
  src_dir            Directory with with binary files. Defaults to ~/.touca/results.
  out_dir            Directory with modified files. Defaults to ~/.touca/modified.

options:
  --filter FILTER    Limit results to a given suite or version. Value should be in form of suite[/version].
  --team TEAM        new value for the team slug
  --suite SUITE      new value for the suite slug
  --version VERSION  new value for the version slug

By design, Touca archive files include the metadata for each test case including team, suite and version. You can use touca results edit to modify these metadata fields in binary archives before submitting them to the Touca server.

$ touca results edit --filter students --suite students_2

students/v5.1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
students/v5.2 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
students/v5.3 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00