Usetrace allows you to run traces from your GitLab CI/CD pipelines, helping to catch issues early in your development process. This guide will walk you through setting up and using Usetrace in your GitLab projects.

Prerequisites

A GitLab repository
A Usetrace account with existing traces or projects
Basic familiarity with GitLab CI/CD (You can refer to: https://docs.gitlab.com/ee/ci/quick_start/)

Setting up your pipeline

1. In your repository on GitLab.com, create a GitLab CI/CD pipeline configuration file called for example .gitlab-ci.yml in the root directory of your repository. You can do this from the GitLab UI:

If the .gitlab-ci.yml file does not exist, go to the main page of the repository on GitLab:
Open the drop-down with a plus symbol
↳Click New file
↳Name the file .gitlab-ci.yml.
If the file .gitlab-ci.yml already exists in the root of your repo, you can edit it by clicking on it and then selecting the Edit drop-down

GitLab will detect the presence of the file .gitlab-ci.yml and run the jobs of your stages.

2. Copy the following YAML contents into the .gitlab-ci.yml file:

include:
  - remote: 'https://gitlab.com/usetrace/gitlab-jobs/-/raw/main/run-trace-job.yml'
    inputs:
      # Requred input
      traceId: "{Trace Id}"
      # Here you can use optional inputs like:
      browsers: "chrome, firefox"

stages:
  - run-trace

run_a_trace:
  extends: .run_trace_job
  stage: run-trace

3. The .run_trace_job has one mandatory input:

traceId: The ID of your Usetrace trace or project.

Replace the {Trace Id} in the yml with the Id of one of your Traces. It's recommended to store the traceId input as a variable in your repository variables.

How to find the Id of your Trace

You can find it by selecting the project that contains the Trace you want to trigger in your Usetrace account and then:
Click All Traces in the top navigation bar
↳ Click on the Trace you want to trigger to open it
↳ Copy the last part of the URL of your browser

You will have a URL like this: https://team.usetrace.com/editor/#trace/ZoMvAy6weAAXXcb3jfGGG9QPEvnsqTNY and you need to copy the last part. In this case: ZoMvAy6weAAXXcb3jfGGG9QPEvnsqTNY

How to find the Id of your Project

You can find it by selecting the project in your Usetrace and then:
Click Preferences in the top navigation bar
↳ Click on Project in the left menu
↳ Scroll down and you will find the field Project ID

It will look something like this: ZodMfx6ReAAXXca7VhlygnfF8lGO5Pok

4. Now once any change is pushed, the workflow will run, it will trigger the Trace you configured and wait for it to finish.

Current templates:

run-trace-job.yml: Allows you to extend a job with `.run-trace-job`. Which will allow you to trigger a single trace.
run-project-job.yml: Allows you to extend a job with `.run-project-job`. Which will allow you to trigger the traces of an entire project.

You can find more information about importing GitLab templates here:
https://docs.gitlab.com/ee/ci/yaml/index.html#includeremote

Inputs

Required Inputs

To use extend from the job .run-trace-job (run-trace-job.yml):

traceId: ID of a valid Usetrace Project or Trace to be triggered.

To use extend from the job .run-project-job (run-project-job.yml):

projectId: ID of a valid Usetrace Project or Trace to be triggered.

Optional Inputs

General Arguments

browsers: Comma-separated list of browsers (e.g., 'chrome, firefox') If none is specified then tests will run in Chrome.
baseUrl: Base URL to execute against (defaults to the project base URL).
parameters: Object trace parameters. You can pass them as JSON attributes. Ex: '"key1": "value1", "key2": "value2"',.
usetraceApiKey: Usetrace API Key for authentication.
buildTimeoutSeconds: Maximum time to wait for the build before timing out the workflow. Default: 3600 seconds (60 minutes).

Workflow Control

failOnFailedTraces: Determines whether the workflow should fail if any traces fail. Set to 'true' to fail the workflow if the count of failed traces is not zero, and to 'false' to always pass the workflow regardless of trace results. Default: 'true'.

Reporter Webhook

You can tell Usetrace to notify when the build finishes using the Reporter Webhook and personalize its behavior.

webhookUrl: URL of the POST callback to send the result. You must include this value if you want a webhook to be invoked when the build finishes.
webhookWhen: Designation of when the webhook should be triggered. Available values: 'always', 'fails' (on failures only), 'changes' (on result changes only). Default: 'always'.
webhookSecretkey: If provided, a HMAC signature will be created and passed via a Signature header to verify the validity of the POST response payload.
webhookUsername: Username for basic auth if the callback URL is behind an auth wall.
webhookPassword: Password for basic auth.

Project-Only Arguments

These arguments only work if you are triggering the job .run-project-job of the template run-project-job.yml:

tags: Comma-separated list of tags. Only traces with those tags will be run (by default run all Traces).
commit: of the commit leading to this build.
commitLink: Link to the commit.

Output artifact

The builds generate an artifact in the root folder called output.json with the following fields:
id: Build ID executed.

status: Status of the run.

request: Count of requested traces.

finish: Count of finished traces.

pass: Count of passed traces.

fail: Count of failed traces.

report: Full JSON report of the build.

Here is an example report:

{
  "name": "Environment: https://www.wikipedia.org/",
  "tests": 2,
  "traces": 1,
  "expectedTracesToPass": 0,
  "tracesPassed": 1,
  "errors": 0,
  "failures": 0,
  "skip": 0,
  "bugs": 0,
  "bugsPassing": 0,
  "buildStable": true,
  "testCase": [
    {
      "className": "Usetrace.trace",
      "name": "chrome: Test Wikipedia",
      "time": 1.192,
      "error": null,
      "browserName": "chrome",
      "traceName": " Test Wikipedia",
      "taggedBug": false,
      "taggedFlaky": true
    },
    {
      "className": "Usetrace.trace",
      "name": "firefox: Test Wikipedia",
      "time": 1.74,
      "error": null,
      "browserName": "firefox",
      "traceName": " Test Wikipedia",
      "taggedBug": false,
      "taggedFlaky": true
    }
  ]
}

You can access all values of the report in the other jobs of your pipeline using the generated report artifact.

Please take a look at the official Usetrace documentation for more detailed information on creating and managing your tests.

Here are some more resources you should check:

It might help you have a look at the readme of our GitLab Templates repository: https://gitlab.com/usetrace/gitlab-jobs
You can learn more about how to integrate with Usetrace by looking into this doc:
https://docs.usetrace.com/en/collections/167106-api-and-continuous-integration-ci
If you want to learn more about GitLab CI/CD pipelines and how to configure them:
https://docs.gitlab.com/ee/ci/quick_start/