chore(docs): Reflect the Transactions to Test Suites (#3051)

* chore(docs): Updating the Docs to reflect the Transactions to Test Suite Changes

* PR review comments and redirects

* fixing typos

* cleanup

docs/docs/ci-cd-automation/github-actions-pipeline.md

@@ -56,7 +56,7 @@ jobs:
       run: |
         tracetest run test -f ./tracetest/tests/test-api.yaml
         tracetest run test -f ./tracetest/tests/test-api-and-av.yaml
-        tracetest run transaction -f ./tracetest/tests/transaction-api.yaml
+        tracetest run testsuite -f ./tracetest/tests/testsuite-api.yaml
 
     - name: Stop containers
       if: always()
@@ -96,7 +96,7 @@ jobs:
       run: |
         tracetest run test -f ./tracetest/tests/test-api.yaml
         tracetest run test -f ./tracetest/tests/test-api-and-av.yaml
-        tracetest run transaction -f ./tracetest/tests/transaction-api.yaml
+        tracetest run testsuite -f ./tracetest/tests/testsuite-api.yaml
 
     - name: Stop containers
       if: always()
@@ -479,12 +479,12 @@ spec:
     - attr:isAvailable = "true"
 ```
 
-The transaction `transaction-api.yaml` will run both the tests above.
+The testsuite `testsuite-api.yaml` will run both the tests above.
 
 ```yaml
-# ./tracetest/tests/transaction-api.yaml
+# ./tracetest/tests/testsuite-api.yaml
 
-type: Transaction
+type: TestSuite
 spec:
   id: 3YIB7rPVg
   name: All Tests for the Books List API

docs/docs/cli/creating-test-outputs.md

@@ -1,10 +1,10 @@
 # Defining Test Outputs in Text Files
 
-Outputs are really useful when running [Transactions](../concepts/transactions). They allow for exporting values from a test so they become available in the [Variable Sets](../concepts/variable-sets.md) of the current transaction.
+Outputs are really useful when running [Test Suites](../concepts/test-suites). They allow for exporting values from a test so they become available in the [Variable Sets](../concepts/variable-sets.md) of the current Test Suite.
 
 ## Outputs are Expression Results
 
-An output exports the result of an [Expression](../concepts/expressions) and assigns it to a name, so it can be injected into the variable set of a running transaction.
+An output exports the result of an [Expression](../concepts/expressions) and assigns it to a name, so it can be injected into the variable set of a running Test Suite.
 A `selector` is needed only if the provided expression refers to a/some span/s attribute or meta attributes.
 
 It can be defined using the following YAML definition:
@@ -33,7 +33,7 @@ outputs:
 
 - name: INTERPOLATE_STRING
   # assume PRE_EXISTING_VALUE=someValue from env vars
-  value: "the value ${env:PRE_EXISTING_VALUE} comes from the env var PRE_EXISTING_VALUE"
+  value: "the value ${var:PRE_EXISTING_VALUE} comes from the env var PRE_EXISTING_VALUE"
   # results in INTERPOLATE_STRING = "the value someValue comes from the env var PRE_EXISTING_VALUE
 ```
 

docs/docs/cli/creating-test-suites.md

@@ -0,0 +1,31 @@
+# Defining Test Suites as Text Files
+
+This page showcases how to create and edit Test Suites with the CLI.
+
+:::tip
+[To read more about Test Suites check out Test Suites concepts page.](../concepts/test-suites.md)
+:::
+
+Just like other structures of Tracetest, you can also manage your Test Suites using the CLI and definition files.
+
+A definition file for a Test Suite looks like the following:
+
+```yaml
+type: TestSuite
+spec:
+  name: Test purchase flow
+  description: Test a flow of purchasing an item
+  steps:
+    - ./tests/create-product.yaml
+    - ./tests/add-product-to-cart.yaml
+    - ./tests/complete-purchase.yaml
+    - testID # you can also reference tests by their ids instead of referencing the definition file
+```
+
+In order to apply this Test Suite to your Tracetest instance, make sure to have your [CLI configured](./configuring-your-cli.md) and run:
+
+```sh
+tracetest apply testsuite -f <testsuite.yaml>
+```
+
+> If the file contains the property `spec.id`, the operation will be considered a Test Suite update.

docs/docs/cli/running-transactions.md → docs/docs/cli/running-test-suites.md

@@ -1,38 +1,38 @@
-# Running Transactions From the Command Line Interface (CLI)
+# Running Test Suites From the Command Line Interface (CLI)
 
-Once you have created a transaction, whether from the Tracetest UI or via a text editor, you will need the capabity to run it via the Command Line Interface (CLI) to integrate it into your CI/CD process or your local development workflow.
+Once you have created a Test Suite, whether from the Tracetest UI or via a text editor, you will need the capability to run it via the Command Line Interface (CLI) to integrate it into your CI/CD process or your local development workflow.
 
-The command to run a transaction is the same as running a test from the CLI.
+The command to run a Test Suite is the same as running a test from the CLI.
 
 The documentation for running a test via the CLI can be found here:
 
 - [tracetest run](./reference/tracetest_run.md): This page provides examples of using this command.
 
-## Running Your First Transaction
+## Running Your First Test Suite
 
-To run a transaction, give the path to the transaction definition file with the `'-f'` option. This will launch a transaction, providing us with a link to the created transaction run.
+To run a Test Suite, give the path to the Test Suite definition file with the `'-f'` option. This will launch a Test Suite, providing us with a link to the created Test Suite run.
 
 ```sh
-tracetest run transaction -f path/to/transaction.yaml
+tracetest run testsuite -f path/to/testsuite.yaml
 ```
 ```text title="Output:"
-✔ Pokemon Transaction (http://localhost:11633/transaction/xcGqfHl4g/run/3)
+✔ Pokemon Test Suite (http://localhost:11633/testsuite/xcGqfHl4g/run/3)
 	✔ Pokeshop - Import (http://localhost:11633/test/XRHjfH_4R/run/4/test)
 	✔ Pokeshop - List (http://localhost:11633/test/QvPjBH_4g/run/4/test)
 ```
 
-## Running a Transaction That Uses Variable Sets
+## Running a Test Suite That Uses Variable Sets
 
-There are two ways of referencing a variable set when running a transaction.
+There are two ways of referencing a variable set when running a Test Suite.
 
 You can reference an existing variable set using its id. For example, given this defined variable set with an id of `'testenv'`:
 
 ![testenv](../img/show-environment-definition.png)
 
-We can run a transaction and specify that variable set with this command:
+We can run a Test Suite and specify that variable set with this command:
 
 ```sh
-tracetest run transaction -f path/to/transaction.yaml --vars testenv
+tracetest run testsuite -f path/to/testsuite.yaml --vars testenv
 ```
 
 You can also reference a variable set resource file which will be used to create a new variable set or update an existing one. For example, if you have a file named `local.env` with this content:
@@ -50,7 +50,7 @@ spec:
 ```
 
 ```sh
-tracetest run test -f path/to/transaction.yaml --vars path/to/local.env
+tracetest run test -f path/to/testsuite.yaml --vars path/to/local.env
 ```
 
 If you use the variable set resource approach, a new variable set will be created in Tracetest.

docs/docs/cli/running-tests.md

@@ -1,6 +1,6 @@
 # Running Tests From the Command Line Interface (CLI)
 
-Once you have created a test, whether from the Tracetest UI or via a text editor, you will need the capabity to run it via the Command Line Interface (CLI) to integrate it into your CI/CD process or your local development workflow.
+Once you have created a test, whether from the Tracetest UI or via a text editor, you will need the capability to run it via the Command Line Interface (CLI) to integrate it into your CI/CD process or your local development workflow.
 
 The documentation for running a test via the CLI can be found here:
 

docs/docs/cli/undefined-variables.md

@@ -1,6 +1,6 @@
 # Undefined Variables
 
-When a user runs a test or a transaction, any variables that will be needed but are not defined will be prompted for:
+When a user runs a test or a Test Suite, any variables that will be needed but are not defined will be prompted for:
 
 ```sh
 tracetest run test -f path/to/test.yaml
@@ -13,7 +13,7 @@ POKEID:
 POKENAME:
 ```
 
-Undefined variables are dependent on the variable set selected and whether or not the variable is defined in the current variable set. Select the variable set to run the test or transaction by passing it into the test run command.
+Undefined variables are dependent on the variable set selected and whether or not the variable is defined in the current variable set. Select the variable set to run the Test or Test Suite by passing it into the test run command.
 
 ```sh
 tracetest list variableset

docs/docs/concepts/ad-hoc-testing.md

@@ -14,21 +14,21 @@ This page showcases use-cases for undefined variables and how to enable ad-hoc t
 
 ### **Supply Variable Value at Runtime**
 
-A user wants a test or transaction they can run on a particular user, order id, etc. that is configurable at run time. This makes running an adhoc test in an environment, even production, very easy and convenient. In this case, the user references the variable, but doesn't add it to the environment. Each time they run the test or transaction, they will be prompted for the unspecified variables.
+A user wants a Test or Test Suite they can run on a particular user, order id, etc. that is configurable at run time. This makes running an adhoc test in an environment, even production, very easy and convenient. In this case, the user references the variable, but doesn't add it to the environment. Each time they run the Test or Test Suite, they will be prompted for the unspecified variables.
 
 ### **Supply Variable Value from a Previous Test**
 
-A user wants to define 3 tests as part of a transaction. The first test has an output variable and this output is used by the second test. They define the first test. They then define the second test and reference the variable value that is output from the first test. 
+A user wants to define 3 tests as part of a Test Suite. The first test has an output variable and this output is used by the second test. They define the first test. They then define the second test and reference the variable value that is output from the first test. 
 
 In Tracetest, undefined variables can be used in both the UI and CLI. 
 
-## **Undefined Variables Transaction with Multiple Tests Example**
+## **Undefined Variables Test Suite with Multiple Tests Example**
 
 1. Create an HTTP Pokemon list test that uses variables for hostname and the SKIP query parameter:
 
 ![Create Pokemon List](../img/pokeshop-list.png)
 
-1. Within the test, create test spec assertions that use variables for comparators, something like: `http.status_code = "${env:STATUS_CODE}"`:
+1. Within the test, create test spec assertions that use variables for comparators, something like: `http.status_code = "${var:STATUS_CODE}"`:
 
 ![Create Test Spec Assertionsl](../img/create-test-spec-assertions.png)
 
@@ -40,10 +40,10 @@ In Tracetest, undefined variables can be used in both the UI and CLI.
 
 ![Test Output](../img/test-output.png)
 
-5. Now, you can create a transaction with the two tests - first, add the list test, then the add test, and then the list test again:
+5. Now, you can create a Test Suite with the two tests - first, add the list test, then the add test, and then the list test again:
 
-![Create Transaction](../img/create-transaction.png)
+![Create Test Suite](../img/create-testsuite.png)
 
 6. From here you can input the values for the undefined variables and complete your trace:
 
-![Input Values](../img/input-values.png)
+![Input Values](../img/input-values.png)

docs/docs/concepts/test-suites.md

@@ -0,0 +1,60 @@
+# Test Suites
+
+Most End-to-End tests are not simple to run. They require some setup before the actual test is run. Actions like creating a new user, removing all items from a cart, etc. It is important that you can execute multiple steps as part of your Test Suite. Tracetest introduces the concept of **Test Suites** to achieve this goal.
+
+## What is a Test Suite?
+A Test Suite is defined as a group of steps that are executed in the defined order and can access information exported by previous step executions. Each step is a test.
+
+## Chaining Tests
+The main benefit of using Test Suites is to chain tests together and use values obtained from a test in a subsequent test.
+
+### How Values are Shared by Tests
+When a Test Suite is run, a context object is created with information about that specific run. One of those pieces of information is a `variable set` object, which is empty by default. If the Test Suite is run when referencing an [variable set](./variable-sets.md), all values from the selected variable sets will be copied to the `variable set` object.
+
+When a test is executed within a Test Suite, if it generates any outputs, its outputs will be injected into the Test Suite context variable set object. After the outputs are injected, all subsequent tests to be run within the Test Suite will be able to reference those values.
+
+> :information_source: Outputs generated by steps don't modify the selected [variable set](./variable-sets.md). It only modifies the Test Suite run context object.
+
+Consider you have 3 tests within a Test Suite: A, B, and C. Tests A and B generate outputs called A_OUTPUT and B_OUTPUT, respectively. When running the Test Suite, we provide a variable set which contains a `HOST` variable. The execution of test A would only be able to reference `var:HOST`. B would be able to reference `var:HOST`, and `var:A_OUTPUT`. While C would be able to reference all three variables: `var:HOST`, `var:A_OUTPUT`, `var:B_OUTPUT`.
+
+> :information_source: A single test can contain as many outputs as you like.
+
+### Exposing Values from a Test to Other Tests
+Since version v0.8, Tracetest allows tests to declare `outputs`. An output is a value that is extracted from a trace by providing a [selector](./selectors) to choose which spans to use to get the information from, and an [expression](./expressions) to get the value from the selected spans. For example, consider that you want to expose the time a specific job was taken from a queue and began executing. An output would look something like the following:
+
+```yaml
+outputs:
+    - name: TIME_CANCEL_SUBSCRIPTION_MESSAGE_OBTAINED
+      selector: span[name = "Process request from cancel subscription queue"]
+      expression: attr:tracetest.time.start
+```
+
+This would create an output called `TIME_CANCEL_SUBSCRIPTION_MESSAGE_OBTAINED` that is obtained by reading the attribute `tracetest.time.start` from the span with `name` equal to `Process request from cancel subscription queue`. This value would then be injected into the variables of that Test Suite to be accessed by other tests within the same Test Suite run.
+
+### Test Suites Execution Flow
+
+Test Suite steps are executed sequentially. A next step is only executed after the previous step finishes executing successfully. A successful step is one which managed to trigger an operation and received a trace back from the data store. Failing assertions do not stop a Test Suite from executing the next steps.
+
+Examples:
+
+### Test Suite where one step didn't get executed:
+
+* Step 1 (Finished)
+* Step 2 (Failed to fetch trace)
+* Step 3 (not executed)
+
+Result: **FAILED**
+
+### Test Suite where all steps were executed, but the assertions failed:
+* Step 1 (Finished)
+* Step 2 (Finished)
+* Step 3 (Failed assertions)
+
+Result: **FAILED**
+
+### Test Suite where all steps succeeded:
+* Step 1 (Finished)
+* Step 2 (Finished)
+* Step 3 (Finished)
+
+Result: **FINISHED**