If you're interested in contributing code to Bearer, this guide will help you do it. If you haven't already, review the contributing overview for different ways you can contribute.
Set up Bearer locally
Bearer is written in Go, so you'll need golang v1.19 or greater installed. Installation instructions for your architecture can be found at golang downloads page.
Next, confirm the installation by running the following command:
You should receive a response with the installed version and architecture.
With Go installed, Fork and clone the Bearer repository locally using your preferred method. For example:
git clone https://github.com/Bearer/bearer.git
Next, navigate into the Bearer project in your terminal, and install the required go modules:
go mod download
Finally, we use direnv to manage env vars in development. This is primarily used for running tests. You can either:
- Set up your own by using
.envrc.exampleas a base. You're unlikely to need to set anything other than
GITHUB_WORKSPACEfor integration tests, so feel free to skip this step or export it manually using:
- Run tests using the script method mentioned below.
Running Bearer locally from source
To run Bearer from source use the following command from the bearer directory:
go run ./cmd/bearer/main.go [COMMAND]
Use commands and flags as normal in place of
Running tests is best performed using the
run_tests.sh script. This will configure all needed variables to handle both unit and integration tests.
# From the project base ./scripts/run_tests.sh
Alternatively, you can run tests manually. Keep in mind you'll need to include the working path to the
GITHUB_WORKSPACE environment variable if you choose this path.
Run all tests:
go test ./...
Running classification tests:
go test ./pkg/classification/... -count=1
Running a single specific test:
go test -run ^TestSchema$ ./pkg/classification/schema -count=1
These tests work by running an instance of the Bearer application, with a specified set of arguments, and then capturing the standard output and standard error streams. The captured output is compared against a snapshot of the expected output, using the cupaloy library.
The standard pattern is to create test case(s) using the
testhelper.NewTestCase factory function, and then pass these into the
testhelper.RunTests function for execution.
Integration tests are grouped within the top-level
integration subdirectory; see the existing tests for examples
to follow when adding a new test.
To update snapshots, set the
UPDATE_SNAPSHOTS env variable to
true when running a test. For example:
UPDATE_SNAPSHOTS=true go test ./...
Note: you will need to export
GITHUB_WORKSPACE as the full path to the project so integration tests can run correctly. Alternatively, use the
run_tests.sh script method mentioned in the testing section above.
Generating CLI Documentation
Bearer's reference pages are built, in-part, by files created from the CLI source. Whenever updating CLI commands or flags, it's best to rerun the generator below and include the created files in your PR. Upon a new doc build, the docs website will reflect these changes.
From the root of the project run:
go run ./scripts/gen-doc-yaml.go
This will auto generate yaml files for any updated CLI arguments.
If you need help getting set up, or are unsure how to navigate the codebase, join our discord community and we'll be happy to point you in the right direction.