github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/adr/0008-begin-using-unit-tests.md (about)

     1  # 8. Begin using unit tests
     2  
     3  Date: 2022-12-12
     4  
     5  ## Status
     6  
     7  Accepted
     8  
     9  ## Context
    10  
    11  There are sections of the code that are not easily able to be tested by our end-to-end testing and now that Jackal is moving into being a library for other products there will be more scrutiny around our defined interfaces.  This ADR explores ways that we could adjust our testing strategy to address these concerns.
    12  
    13  Potential considerations:
    14  
    15  1. Introduce Unit-Testing Jackal-wide
    16      Pros:
    17          - More of the codebase is covered with tests and will force us to take more consideration when updating it
    18      Cons:
    19          - As the codebase evolves the efficacy of these tests is likely to go down, especially if they are written to the code rather than the interface
    20  
    21  2. Introduce Unit Testing in a defined and limited capacity within Jackal
    22      Pros:
    23          - A decent amount of the codebase will be tested (specifically we can target those areas difficult to e2e test)
    24          - We can be picky about what/where we unit test so that the maintenance burden of the tests is not too high
    25      Cons:
    26          - We will need to be vigilant when PRs come through with Unit Tests that these are correct applications of them
    27  
    28  3. Introduce Integration Testing or partial End-to-End testing
    29      Pros:
    30          - This is closer to how we already test within Jackal
    31      Cons:
    32          - These can be relatively complex to orchestrate and maintain over time requiring complex mocks or other mechanisms to make them work
    33  
    34  ## Decision
    35  
    36  It was decided to introduce a limited set of unit tests to the Jackal codebase (2) because this will enable us the most flexibility and control over how we test while also allowing us to specifically target specific units without a ton of overhead.  Specifically we will ask the following before implementing a Unit Test:
    37  
    38  1. Is what I want to test a true unit (i.e. a single function or file)?
    39  2. Does what I want to test have a clearly defined interface (i.e. a public specification)?
    40  3. Is this code inside of the `src/pkg` folder or should it be?
    41  
    42  ## Consequences
    43  
    44  This will help us to test things like specific file formats or interactions with certain standards more easily and will allow us to define our own function signatures that are well tested for use in library code.  We will need to be vigilant though going forward that any new test follows the guidelines above, and that contributors are aware of when they should introduce a unit test.