github.com/darmach/terratest@v0.34.8-0.20210517103231-80931f95e3ff/docs/_docs/02_testing-best-practices/debugging-interleaved-test-output.md (about)

     1  ---
     2  layout: collection-browser-doc
     3  title: Debugging interleaved test output
     4  category: testing-best-practices
     5  excerpt: >-
     6    Learn more about `terratest_log_parser`.
     7  tags: ["testing-best-practices", "logger"]
     8  order: 206
     9  nav_title: Documentation
    10  nav_title_link: /docs/
    11  ---
    12  
    13  ## Debugging interleaved test output
    14  
    15  **Note**: The `terratest_log_parser` requires an explicit installation. See [Installing the utility
    16  binaries](#installing-the-utility-binaries) for installation instructions.
    17  
    18  If you log using Terratest's `logger` package, you may notice that all the test outputs are interleaved from the
    19  parallel execution. This may make it difficult to debug failures, as it can be tedious to sift through the logs to find
    20  the relevant entries for a failing test, let alone find the test that failed.
    21  
    22  Therefore, Terratest ships with a utility binary `terratest_log_parser` that can be used to break out the logs.
    23  
    24  To use the utility, you simply give it the log output from a `go test` run and a desired output directory:
    25  
    26  ```bash
    27  go test -timeout 30m | tee test_output.log
    28  terratest_log_parser -testlog test_output.log -outputdir test_output
    29  ```
    30  
    31  This will:
    32  
    33  - Create a file `TEST_NAME.log` for each test it finds from the test output containing the logs corresponding to that
    34    test.
    35  - Create a `summary.log` file containing the test result lines for each test.
    36  - Create a `report.xml` file containing a Junit XML file of the test summary (so it can be integrated in your CI).
    37  
    38  The output can be integrated in your CI engine to further enhance the debugging experience. See Terratest's own
    39  [circleci configuration](https://github.com/gruntwork-io/terratest/blob/master/.circleci/config.yml) for an example of how to integrate the utility with CircleCI. This
    40  provides for each build:
    41  
    42  - A test summary view showing you which tests failed:
    43  
    44  ![CircleCI test summary]({{site.baseurl}}/assets/img/docs/debugging-interleaved-test-output/circleci-test-summary.png)
    45  
    46  - A snapshot of all the logs broken out by test:
    47  
    48  ![CircleCI logs]({{site.baseurl}}/assets/img/docs/debugging-interleaved-test-output/circleci-logs.png)
    49  
    50  ## Installing the utility binaries
    51  
    52  Terratest also ships utility binaries that you can use to improve the debugging experience (see [Debugging interleaved
    53  test output](#debugging-interleaved-test-output)). The compiled binaries are shipped separately from the library in the
    54  [Releases page](https://github.com/gruntwork-io/terratest/releases).
    55  
    56  To install a binary, download the version that matches your platform and place it somewhere on your `PATH`. For example
    57  to install version 0.13.13 of `terratest_log_parser`:
    58  
    59  ```bash
    60  # This example assumes a linux 64bit machine
    61  # Use curl to download the binary
    62  curl --location --silent --fail --show-error -o terratest_log_parser https://github.com/gruntwork-io/terratest/releases/download/v0.13.13/terratest_log_parser_linux_amd64
    63  # Make the downloaded binary executable
    64  chmod +x terratest_log_parser
    65  # Finally, we place the downloaded binary to a place in the PATH
    66  sudo mv terratest_log_parser /usr/local/bin
    67  ```
    68  
    69  Alternatively, you can use [the gruntwork-installer](https://github.com/gruntwork-io/gruntwork-installer), which will do
    70  the above steps and automatically select the right binary for your platform:
    71  
    72  ```bash
    73  gruntwork-install --binary-name 'terratest_log_parser' --repo 'https://github.com/gruntwork-io/terratest' --tag 'v0.13.13'
    74  ```
    75  
    76  The following binaries are currently available with `terratest`:
    77  
    78  {:.doc-styled-table}
    79  | Command                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
    80  | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    81  | **terratest_log_parser** | Parses test output from the `go test` command and breaks out the interleaved logs into logs for each test. Integrate with your CI environment to help debug failing tests.                                                                                                                                                                                                                                                                                                                                                                                                            |
    82  | **pick-instance-type**   | Takes an AWS region and a list of EC2 instance types and returns the first instance type in the list that is available in all Availability Zones in the given region, or exits with an error if no instance type is available in all AZs. This is useful because certain instance types, such as t2.micro, are not available in some newer AZs, while t3.micro is not available in some older AZs. If you have code that needs to run on a "small" instance across all AZs in many regions, you can use this CLI tool to automatically figure out which instance type you should use. |