What are the core functions an extension can rely on?

Question

It's been said, quite reasonably, that all APIs should have tests, and that if a feature doesn't have tests then coders shouldn't rely on it.

This raises two three questions:

1. other than direct "API3" calls what can I rely on not to change in the future?
2. how can I know which methods have tests?
3. what is the strategy is for introducing new tests to "lock in" certain useful utility methods?

As one small example, specifically I am talking about the "sub-API-API" - eg these type of methods but also accessing other "system" services (like mail, http, debug logging, UF, UI messenging)

(sorry this maybe a bit wooly for SE, but it is something I have struggled with)

Answer 1

Yes, SE isn't designed to have three questions in one, as this leads to a knotted ball of yarn.

1. API calls are intended to have unchanging interfaces for the life of that version of the API, once the version is marked as stable. Currently API v2 has been retired, API v3 has long been stable, and API v4 is in development.

The nuance you note is that we can only ensure that the results returned by the API are stable if there is a test.

I should also note that if a bug is discovered, eg incorrect tax calculations, then fixing the bug may result in changes to incorrect return values from APIs.

2. Look through the directory for tests. Note that it can be appropriate to have multiple tests for a single method, and we would love to improve the robustness of the use cases we have tests for.

3. The most appropriate place to add a test to lock-in current behaviour for an API is likely https://github.com/civicrm/civicrm-core/tree/master/tests, though there are other types of tests in other directories that might be relevant. For a class like CRM_Utils_System_Base, probably add tests under https://github.com/civicrm/civicrm-core/tree/master/tests/phpunit/CRM/Utils. In terms of making utility methods like these have the 'first order' status of a public API method, this is probably something that deserves community discussion. For example, it might be that we could document somewhere a list of methods that are considered public and stable perhaps in a wiki or preferably to my mind in a docblock. Or it might be decided for consistency and improved Developer Experience to wrap the relevant utility functions in an API wrapper. Could you raise this issue in the dev channel at https://chat.civicrm.org or send a message to [email protected] after adding yourself at https://lists.civicrm.org/lists ?