How to Use Shepherd For Testing

This section explains how to use Shepherd for Testing Projects by generating a Shepherd version and importing Shepherd to your projects.

Generate Shepherd Version

1. GET request to this URL https://proxy.golang.org/github.com/rancher/shepherd/@v/<placeholder>.info

   a. For the main branch replace <placeholder> with the main

   b. For the other release lines it would be the latest commit. So it could look like this https://proxy.golang.org/github.com/rancher/shepherd/@v/cb4bf59.info Where cb4bf59 is the latest commit from either of the supported release lines.

2. A JSON response will be returned that will look like this:

       "Version":"v0.0.0-20240119193844-cb4bf5918ce8",
       "Time":"2024-01-19T19:38:44Z",
       "Origin": {
           "VCS":"git",
           "URL":"https://github.com/rancher/shepherd",
           "Hash":"cb4bf5918ce8f4b17f7fad1c7bc977925045f4b1"
           }
       }
   

Version is what will be used in go get or by updating it in the go.mod file directly.

How to Import Shepherd to a Testing Project

You can import Shepherd as any other go module to your testing project. Run the go command in your testing project: go get github.com/rancher/shepherd@version where version is the version generated above.

How to Test Remote Changes with Shepherd and Your Testing Project

1. GET request to this URL but using your fork https://proxy.golang.org/github.com/<fork>/shepherd/@v/<placeholder>.info

   a. Replace <fork> with your lowercase actual fork and, <placeholder> with your latest commit from your fork and branch

2. In the replace section of your testing project place this line github.com/rancher/shepherd => github.com/<fork>/shepherd <version>

   a. Replace <fork> with your actual fork and <version> with the version you generated from step 1.

3. Run go mod tidy

How to Work Locally with Shepherd and Your Testing Project

While working locally you might want to branch off from the current Shepherd to make changes to your upcoming tests.

1. If you haven't cloned it yet, clone the Shepherd repository.
2. If you haven't imported Shepherd, import it to your testing project.
3. Replace the Shepherd with your local Shepherd clone with go mod edit -replace github.com/rancher/shepherd=local/path/to/shepherd-clone in your testing project. And tidy your go mod file in your testing project with go mod tidy.