DR-000026 - Karate API Integration Tests Implementation Guidelines

Overrides/Supersedes 

This decision was migrated from the Tech Leads Decision Log as part of a consolidation process.  The original decision record can be found here.

RFC 

N/A

Stakeholders

• All Backend Developers

Contributors

Anton Emelianov (Deactivated) 

Approvers

This decision was made by the Tech Leads group prior to the adoption of current decision making processes within the FOLIO project.

Background/Context

Some bugs can only be discovered by integrating modules together. It is challenging to identify these on an ongoing basis.Some integration tests were already implemented. They use Postman collections. They are simple to write but harder to maintain.It can be challenging to express more complex scenarios. Many of which were contributed by ThunderJet team.ThunderJet teams has considered a range of tools and recommend Karate tool. No alternative  proposals has been submitted  therefore Karate framework is preferred method for creating API integration tests in 2020.

Assumptions

N/A

Constraints

N/A

Rationale

Analysis and options

Basically, 2 main alternatives can be suggested for the provided context:

It looks that both options can be viable for FOLIO depending on particular use case.

It worth also noting that UICR-125 - Data corruption. When holding/item data are moved in Inventory, then the item in Courses is not updated accordingly OPENcase is slightly different and is about dangling references while not deletion but moving of a core-module record; neither cascade nor soft deletion is applicable here. At the same time, this case and cascade deletion case have one great similarity - in both, non-core-modules are to be notified about a change in core-module. In this context, a robust notification channel with guaranteed delivery to transfer change events from one module (say, module-source) to another module (say, module-recipient) is required.  More details are on Data consistency and message driven approach # Notification channel.

Soft deletion option

More details regarding this option.

• Q: It requires that every client understands that deleted records might be present and when the API will provide them and when it will not.
  • A: Sure, every client should know the rules of the game. Though once the rules will be agreed and shared, it's just a platform-wide knowledge
• Q: Let's say a loan references an item, that item is then soft-deleted, when the loan is presented in the UI, would the item information be presented or not?
  • A: Yes, the loan is available, and the item information still can be retrieved by a single endpoint. At the same time, loan UI should be able to notify end user that the item has been deleted (via a warning message, or via a dedicated UI field, or via disabling of editing particular values received from the item

High level actions required for core / non-core modules are shown below:

Decision

Implications

• Pros
  • N/A
• Cons
  • N/A

Other Related Resources

Proposed Action Items

• Each team should change definition of done to make API integration tests required
• All new BE features must include Karate tests. 
• R1 Goal: Each team has to create a test plan for existing API interfaces
• R1 Goal: Each team should provide estimates for the test plan. Estimates will be presented at the Capacity Planning meeting so that this work can be officially scheduled into sprints.

Meeting Notes

• GitHub repo and documentation: https://github.com/folio-org/folio-integration-tests
• Karate resources are at the bottom of README.md
• Karate API Integration Testing  implementation tracking page