github.com/openfga/openfga@v1.5.4-rc1/CONTRIBUTING.md (about)

     1  # Contributing to OpenFGA
     2  
     3  Please see our main guide here: https://github.com/openfga/.github/blob/update-contribution-guidelines/CONTRIBUTING.md
     4  
     5  # Testing Guidelines
     6  
     7  OpenFGA strives to maintain good code coverage with tests so that the possibility of regressions is reduced.
     8  
     9  The purpose of this guide is to inform contributors where to write new tests.
    10  
    11  ## 1. Storage layer
    12  
    13  1. Any change to the OpenFGA storage interface must have an integration test in `pkg/storage/test/storage.go`. This is so that anyone writing their own storage adapter can have confidence that it is correct.
    14  
    15  ## 2. API layer
    16  
    17  1. All APIs use an underlying `command` object. These commands must have
    18      1. Unit tests. For example, Write API is backed by Write Command, which has unit tests in `pkg/server/commands/write_test.go`. These should target mocked dependencies to cover the majority of the business logic. If you are changing business logic, add a test in the appropriate commands test file.
    19      2. **Exported** integration tests in `pkg/server/test/server.go`. These take in an unmocked `datastore` dependency. The goal of these is to test that the command and the underlying datastore work well. This is so that anyone who writes their own implementation of the datastore can run these tests by doing
    20  
    21     ```go
    22      import openfgatest "github.com/openfga/openfga/pkg/server/test"
    23      
    24      openfgatest.RunAllTests(t, datastore)
    25      ```
    26  
    27     > NOTE TO MAINTAINERS: ideally, these integration tests shouldn't exist. They are the result of not having enough coverage at the storage interface layer.
    28  
    29  2. Functional tests in `tests/functional_test.go`. These are tests for validating the API inputs and functional API behavior. The inputs are defined in the proto files (https://github.com/openfga/api).
    30  3. Some APIs' behavior can be fine-tuned with server flags. If this is the case, the tests for the correct wiring of the flags live in `pkg/server/server_test.go`.
    31  4. Some APIs set specific response headers. If this is the case, update the test `TestHTTPHeaders` in `cmd/run/run_test.go`.
    32  
    33  ### Query APIs (Check, ListObjects, etc.)
    34  
    35  Take the Check API. Aside from the tests mentioned in "All APIs", it has:
    36  
    37  1. **Exported** integration tests in `tests/check/check.go`. These take in a `client` dependency. This is so that anyone who writes their own version of the server and/or datastore can run these tests by doing
    38      
    39      ```go
    40      import "github.com/openfga/openfga/tests/check"
    41      
    42      check.RunAllTests(t, client)
    43      ```
    44  
    45     The reason these tests live here is because:
    46      - the test cases are defined using easy-to-write YAML files. This enables us to write test cases that apply to all query APIs. (If one Check returns `allowed=true`, the corresponding ListObjects call will, depending on server parameters and other factors, also include it in the response.)
    47      - since these tests are exported, it allows authors of datastores to get extra confidence that their implementations of some methods related to Read of Tuples are correct.
    48  
    49  > NOTE TO MAINTAINERS: ideally, these tests need not be exported, since they are testing for correctness and should be independent of the storage layer. They are the result of not having enough coverage with unit tests.
    50  
    51  2. One test that asserts on the log fields that are emitted: `TestCheckLogs` in `tests/check/check_test.go`.
    52  
    53  > NOTE TO MAINTAINERS: ideally, we have a similar test for other APIs as well.
    54  
    55  ## Docker integration
    56  
    57  OpenFGA can be run within Docker. If changing any of the commands, or changing the Dockerfile itself, the tests in `cmd/openfga/main_test.go` must be updated.