Introduction

Welcome to the Fern Project, an innovative open-source solution designed to enhance Ginkgo test reports. This project is focused on capturing, storing, and analyzing test data to provide insights into test performance and trends. The Fern Project is ideal for teams using Ginkgo, a popular BDD-style Go testing framework, offering a comprehensive overview of test executions and performance metrics.

Integrating the Client into Ginkgo Test Suites

1. Add the Fern dependency to your test project:

   go get -u github.com/guidewire-oss/fern-ginkgo-client/v2

2. Generate Project ID by sending the below payload to fern-reporter (hosted in your environment)

curl -L -X POST http://localhost:8080/api/project \
  -H "Content-Type: application/json" \
  -d '{
    "name": "First Projects",
    "team_name": "my team",
    "comment": "This is the test project"
  }' 

Sample Response:

{
  "uuid": "996ad860-2a9a-504f-8861-aeafd0b2ae29",
  "name": "First Projects",
  "team_name": "my team",
  "comment": "This is the test project"
}

3. Add the Fern Client to your Ginkgo test suite:

   In the example below, from this project, the constant pkg.ProjectName is set to the name of this project:

   const PROJECT_ID = "996ad860-2a9a-504f-8861-aeafd0b2ae29"

   Import the fern client package into the Ginkgo test suite file:

   import fern "github.com/guidewire-oss/fern-ginkgo-client/v2/pkg/client"

   Add ReportAfterSuite to call fern.ReportAfterSuiteSafe, passing the Project ID, the report object, and any ClientOptions. Reporting to Fern is a side effect of running your tests — ReportAfterSuiteSafe logs a warning and returns normally if client creation or the report push fails, so a Fern outage never fails or hangs your test suite.

   var _ = ReportAfterSuite("Fern reporting", func(report Report) {
      fernBaseUrl := "http://localhost:8080/"
       if os.Getenv("FERN_BASE_URL") != "" {
           fernBaseUrl = os.Getenv("FERN_BASE_URL")
       }
       fern.ReportAfterSuiteSafe(pkg.PROJECT_ID, report, fern.WithBaseURL(fernBaseUrl))
   })

   If you need direct control over error handling instead, use fern.New(...) and fernApiClient.Report(report) directly — both return an error you can handle as you see fit.

4. Run Your Tests: After adding the client, run your Ginkgo tests normally.

   ginkgo -r -p --label-filter=unit --randomize-all

5. Authentication: when using the Fern Platform (which has authentication enabled), set the following environment variables:

    export FERN_AUTH_CLIENT_ID=<Your Service Application Client ID>
    export FERN_AUTH_CLIENT_SECRET=<Your Service Application Client Secret>
    export AUTH_URL=<Base URL of your authentication server>
    export FERN_GINKGO_CLIENT_SCOPE=<Fern Platform scope for Testrun write, eg: fern.testrun.write or fern.write>

6. Test Level Tags: if you want to set Test Run level tags, you can do this using an environment variable TEST_RUN_TAGS which can be set to one or more values, separated by commas. For example:

   export TEST_RUN_TAGS="Tag1,Tag2"

7. Environment: if you want to set the Environment, which is stored in the Test Run in Fern, you can do this using an environment variable TEST_ENVIRONMENT. For example:

   export TEST_ENVIRONMENT="local"

See Also

1. Fern UI
2. Fern Ginkgo Reporter