...
- Use Mockito and dependency injection to isolate unit test functionality.
- For SynapseWebClient mocking specifics, see SWC Developer Best Practices
- All bug fixes should be accompanied by a test that provokes the old bug.
- (this is just a start, please add more)
To make a breaking API change to a web service
A breaking API change can be a web service which is removed, a change to request parameters, or a change to a request or response body.
If we can reasonably be sure that a service change will not affect existing clients or applications, the change can be made freely. (This is usually the case with new services, not yet adopted by users.) . Otherwise breaking API changes should proceed along the following steps:
- Note the change in the web service documentation. A service or schema field to be removed can be marked as 'deprecated'.
- Open Jira issues to modify clients to adopt to the change (e.g., to stop using a deprecated service).
- After clients are modified, use the Synapse data warehouse to verify users have updated clients, and hence are no longer affected by the planned change. If there are just a few lingering users of out of date clients, it should be the judgment of the Synapse Product Manager as to whether it's OK to proceed.
- Proceed with the breaking API change.
To insure against breaking API changes
As part of the weekly deployment process, the integration test suites for the currently supported R and Python clients are run against the new stack, which is 'staged' for release. Test failures will occur only if a breaking API change has been introduced to the back end, without following the procedure described above. If so, either (1) the breaking change is to be removed from the staged back-end or (2) the client(s) must be updated to work with the back-end change. Due to the time scale of back end release (weekly) versus client adoption (on the order of months), doing (2) will risk causing failure of some installed client. Therefore (2) should only be done when (a) there is a strong driver for the API change and (b) the chance of affecting existing workloads is low. Such a decision should reflect the judgment of the Synapse Product Manager.