# Running Tests

## Unit Tests <a href="#unit-tests" id="unit-tests"></a>

Your Unit Tests executed via the `go test` will automatically be reported after instrumenting your Go application project with the `scan` command. The default test stage name will be `Unit Tests` but can be changed to anything matching your requirements via the environment variable `SEALIGHTS_TEST_STAGE` updated just before executing the tests.

{% hint style="info" %}
If you want to skip the capture of coverage for `Unit Tests` by the Sealights Golang agent, please set `SEALIGHTS_DISABLE` environment variable as `true` just before triggering Go Unit Tests
{% endhint %}

## Functional Tests <a href="#functional-tests" id="functional-tests"></a>

You can capture coverage, report the test results, and benefit from Sealights Test Optimization by instrumenting your functional tests with the Sealights agent. You are required to provide the Sealights Test Stage execution parameters (token, test stage name, and Lab ID) via environment variables and then execute your scan command according to the framework you’re using

{% code overflow="wrap" lineNumbers="true" %}

```sh
SEALIGHTS_AGENT_TOKEN=$(cat ./sealights/sltoken.txt)
SEALIGHTS_LAB_ID="my_lab_id"
SEALIGHTS_TEST_STAGE="Functional Tests"
#run the scan command
```

{% endcode %}

### Framework relying on `go test` <a href="#framework-relying-on-go-test" id="framework-relying-on-go-test"></a>

If you’re executing your tests with frameworks like **Godog**, **Testify,** and **GoConvey,** which rely on the `go test` under the hood, the `scan` command on the testing project folder should be executed with the flags `--tests-runner` as follows

{% code overflow="wrap" lineNumbers="true" %}

```sh
./sealights/slcli scan --tests-runner --workspacepath "$(pwd)/MyTests" --path-to-scanner ./sealights/slgoagent --scm none
```

{% endcode %}

Then, you can run your regular `go test`command.

### Using Ginkgo <a href="#using-ginkgo" id="using-ginkgo"></a>

When using the Ginkgo framework specifically, you need to run the `scan` command on the Ginkgo project folder with the flags `--tests-runner --enable-ginkgo` as follows

{% hint style="warning" %}
If your **tests are written exclusively using Ginkgo's Domain-Specific Language (DSL)** — which employs specialized syntax and constructs such as `Describe`, `Context`, and `It` — and do not rely on the standard Go `testing.T` type, you can disable instrumentation, reporting, and optimization of the `testing.T` Type by the Sealights agent by setting the environment variable `SEALIGHTS_IGNORE_GO_TESTS` to `true` (default is `false`). The Ginkgo DSL Tests will remain instrumented.
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```sh
SEALIGHTS_IGNORE_GO_TESTS=true
./sealights/slcli scan --tests-runner --enable-ginkgo --workspacepath "$(pwd)/Functional API Tests" --path-to-scanner ./sealights/slgoagent --scm none 
```

{% endcode %}

Then, you can run your regular `ginkgo` command.

### Environment variables for Golang-based test runner executions <a href="#environment-variables-for-golang-based-test-runner-executions" id="environment-variables-for-golang-based-test-runner-executions"></a>

<table><thead><tr><th width="242.666748046875">Environment Variable Name</th><th width="139.6666259765625">Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>SEALIGHTS_LAB_ID</code></td><td>BuildSession Id</td><td>Setting Lab ID</td></tr><tr><td><code>SEALIGHTS_AGENT_TOKEN</code></td><td>-</td><td>Access token generated from the SeaLights server</td></tr><tr><td><code>SEALIGHTS_BUILD_SESSION_ID</code></td><td>-</td><td>(Deprecated) The BuildSession ID of the Application Under Test. Use <code>SEALIGHTS_LAB_ID</code> instead.</td></tr><tr><td><code>SEALIGHTS_TEST_STAGE</code></td><td></td><td>Name of the test stage to appear in the dashboard.</td></tr><tr><td><code>SEALIGHTS_PROXY_URL</code></td><td>““</td><td>Proxy URL for connection to the SL server.</td></tr><tr><td><code>SEALIGHTS_TEST_SELECTION</code></td><td><code>TRUE</code></td><td>Set to <code>false</code> to ignore Test Recommendation locally and execute all the tests (Enforces full run).</td></tr><tr><td><code>SEALIGHTS_IGNORE_GO_TESTS</code></td><td><code>false</code></td><td>Disable integration with the <code>testing.T</code> type for Go tests (Option commonly used with Ginkgo FW integration)</td></tr><tr><td><code>SEALIGHTS_LOG_LEVEL</code></td><td><code>info</code></td><td>Min log level: “<code>debug</code>", "<code>info</code>", "<code>warn</code>", "<code>error</code>"</td></tr></tbody></table>

## Running Your Tests with the Legacy Approach <a href="#running-your-tests-with-the-legacy-approach" id="running-your-tests-with-the-legacy-approach"></a>

When using the SeaLights Go Agent to run your tests, you can follow the legacy approach using three key CLI commands: `start-session`, `upload-results`, and `end-session`. This method helps in reporting and capturing coverage data effectively for your Go applications. The following steps are to follow:

1. **Start Session**: This command initializes a Test Stage Run for your build, which will be used to link all related test and coverage data. It's critical for associating results from different test stages.
2. **Run Your Tests:** Assuming your application under test is properly instrumented with Sealights
3. **Upload Results**: After executing your tests, you need to upload the test results.
4. **End Session**: Conclude the session to finalize the data collection. This ensures that the session is properly closed and all related data (coverage and test results) is processed.

{% hint style="info" %}
This approach doesn’t support Test Optimization.
{% endhint %}

### Sample Script in Bash <a href="#sample-script-in-bash" id="sample-script-in-bash"></a>

Below is a sample script demonstrating the use of `slcli` commands for managing tests in a Go application. Modify the script to suit your specific directory structure, testing framework, and specific environment variables.

{% code overflow="wrap" %}

```sh
#!/bin/bash

# Initialize the Go Agent configuration
./slcli config init --lang go --token ./sltoken.txt

# Notify that a new test session is starting
./slcli start-session --token "$SL_TOKEN" --sessionid "$SESSION_ID"

# Execute your tests
go test ./...

# Upload test results after execution
./slcli upload-results --token "$SL_TOKEN" --sessionid "$SESSION_ID" --results-dir ./test-results

# End the session to ensure proper data processing
./slcli end-session --token "$SL_TOKEN" --sessionid "$SESSION_ID"
```

{% endcode %}