github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/docs/12-contribute-to-jackal/2-testing.md (about)

     1  # Code Testing
     2  
     3  
     4  
     5  Currently, we primarily test Jackal through a series of end-to-end tests located in the [e2e directory](https://github.com/Racer159/jackal/tree/main/src/test/e2e) of the project. This directory houses all of the e2e tests that we use to verify Jackal's functionality in an environment that replicates a live setting. The tests in this directory undergo automatic execution against several K8s distros whenever a pull request is created or updated. Through this testing, we ensure that Jackal performs consistently across a range of K8s environments, ensuring its reliability for users.
     6  
     7  In addition, Jackal undergoes a series of unit tests for specific functions where edge cases prove difficult to cover through end-to-end testing alone. You can locate these tests in the [src/pkg directory](https://github.com/Racer159/jackal/tree/main/src/pkg), where they are identified by `*_test.go` files.
     8  
     9  ## Dependencies
    10  
    11  To run the end-to-end tests locally, you must meet the same prerequisites as those required for building and running Jackal, which include:
    12  
    13  1. GoLang >= `1.19.x`.
    14  2. Make.
    15  3. Any clean K8s cluster (local or remote) or Linux with sudo if you want to use the Jackal-installed K3s cluster.
    16  4. NodeJS >= `18.x.x`.
    17  
    18  ### CLI End-to-End Tests
    19  
    20  There are several ways to run tests depending on your specific situation, such as:
    21  
    22  ``` bash
    23  # Note: You can prepend CI=true to these commands to force the --no-progress flag like CI does
    24  
    25  # The default way, from the root directory of the repo. Will run all of the tests against your chosen k8s distro. Will automatically build any binary dependencies that don't already exist.
    26  make test-e2e ARCH="[amd64|arm64]"
    27  
    28  # To test against a Jackal-created cluster (on Linux with sudo)
    29  APPLIANCE_MODE=true make test-e2e ARCH="[amd64|arm64]"
    30  
    31  # If you already have everything build, you can run this inside this folder. This lets you customize the test run.
    32  go test ./src/test/... -v -failfast -count=1
    33  
    34  # Let's say you only want to run one test. You would run:
    35  go test ./src/test/... -v -failfast -run TestFooBarBaz -count=1
    36  ```
    37  
    38  :::note
    39  The `-count=1` flag is the idiomatic way to disable
    40  test caching explicitly.
    41  :::
    42  
    43  :::note
    44  The Jackal binary and built packages are required to be stored in the ./build directory. However, if you intend to run tests locally using 'go test ./...', the jackal-init package must also be present in this directory.
    45  :::
    46  
    47  ### Adding New CLI End-to-End Tests
    48  
    49  When adding new tests, there are several requirements that must be followed, including:
    50  
    51  1. Tests cannot be run in parallel as they utilize the same K8s cluster.
    52  2. Each test should begin with the entries below for standardization and test setup/teardown:
    53  
    54  ```go
    55  func TestFooBarBaz(t *testing.T) {
    56      t.Log("E2E: Enter useful description here")
    57      e2e.setup(t)
    58      defer e2e.teardown(t)
    59  
    60      ...
    61  }
    62  ```
    63  
    64  ### CLI End-to-End Test Naming Conventions
    65  
    66  The end-to-end tests are run sequentially and the naming convention is set intentionally:
    67  
    68  - 00-19 tests run prior to `jackal init` (cluster not initialized).
    69  
    70  :::note
    71  Tests 20+ should call `e2e.setupWithCluster(t)` instead of `e2e.setup(t)`.
    72  
    73  Due to resource constraints in public GitHub runners, K8s tests are only performed on Linux.
    74  :::
    75  
    76  - 20 is reserved for `jackal init`.
    77  - 21 is reserved for logging tests so they can be removed first (they take the most resources in the cluster).
    78  - 22 is reserved for tests required the git-server, which is removed at the end of the test.
    79  - 23-98 are for the remaining tests that only require a basic Jackal cluster without logging or the git-server.
    80  - 99 is reserved for the `jackal destroy` and [YOLO Mode](../../examples/yolo/README.md) test.
    81  
    82  ## CLI Unit Tests
    83  
    84  ### Running CLI Unit Tests
    85  
    86  There are several ways to run tests depending on your specific situation, such as:
    87  
    88  ``` bash
    89  # The default way, from the root directory of the repo. Will run all of the unit tests that are currently defined.
    90  make test-unit
    91  
    92  # If you already have everything built, you can run this inside this folder. This lets you customize the test run.
    93  go test ./src/pkg/... -v
    94  
    95  # Let's say you only want to run one test. You would run:
    96  go test ./src/pkg/... -v -run TestFooBarBaz
    97  ```
    98  
    99  ### Adding New CLI Unit Tests
   100  
   101  When adding new unit tests, please ensure that the following requirements are met:
   102  
   103  1. The test must focus on a true unit, such as a single function or file.
   104  2. The code being tested must have a clearly defined interface, such as a public specification.
   105  3. The code being tested should be located within the `src/pkg`.
   106  
   107  If all these requirements are met, then a unit test would be appropriate. If not, please consider writing an end-to-end test instead or modify your approach to meet these requirements.
   108  
   109  To create a unit test, search for or create a file that ends with `_test.go` in the package of the file that requires testing, such as `auth.go` -> `auth_test.go`. Import the testing library and create test functions as necessary. In case you need to mock something out, determine the most suitable approach and if the mock can be used in multiple tests, consider placing it in  `./src/test/mocks/`. This will help enhance the efficiency and organization of the unit tests.