Running your Tests

Unit Tests

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.

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

Functional Tests

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, Build Session ID and/or Lab ID) via environment variables and then execute your scan command according to the framework you’re using

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

Framework relying on go test

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

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

Then, you can run your regular go testcommand.

Using Ginkgo

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

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.

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

Then, you can run your regular ginkgo command.

Environment variables for Golang-based test runner executions

Environment Variable Name	Default Value	Description
SEALIGHTS_LAB_ID	BuildSession Id	Setting Lab ID
SEALIGHTS_AGENT_TOKEN	-	Access token generated from the SeaLights server
SEALIGHTS_BUILD_SESSION_ID	-	The BuildSession ID of the Application Under Test. Optional if LabID is provided.
SEALIGHTS_TEST_STAGE		Name of the test stage to appear in the dashboard.
SEALIGHTS_PROXY_URL	““	Proxy URL for connection to the SL server.
SEALIGHTS_TEST_SELECTION	TRUE	Set to false to ignore Test Recommendation locally and execute all the tests (Enforces full run).
SEALIGHTS_IGNORE_GO_TESTS	false	Disable integration with the testing.T type for Go tests (Option commonly used with Ginkgo FW integration)
SEALIGHTS_LOG_LEVEL	info	Min log level: “debug", "info", "warn", "error"

Running Your Tests with the Legacy Approach

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.

This approach doesn’t support Test Optimization.

Sample Script in Bash

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.

#!/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"