We have introduced an optional Options parameter, instead of the optional Reporter parameter. The following is the history and reasoning for making this change, as well as our plans to roll it out.
For information on using Options itself, see Options.
With the addition of Scrubbers, we realised that ApprovalTests has some optional parameters. The only one we had of these before was reporter. Because of that, we decided to group together all of the options in to a single container object. This gives us a few advantages:
- We can expand in the future without changing the API.
- Adding functionality becomes simpler, because it passes through to a single place.
It is effectively preparing to use the "Introduce Parameter Object" refactoring pattern.
Our current pattern is to have an optional Reporter at the end of any verify() method.
We are switching this to have an option Options object instead.
This temporarily doubles our API interface, and we are deprecating the Reporter overloads. When enabled, these deprecation warnings will show up as:
- compiler C++14 and above, using the
[[deprecated("..."]]feature - messages on std::cout in C++11
Historically, we have found that it is easier for users to update code for breaking changes if these changes are rolled out in a graduated way. This allows users to select which version of the library to use, to have the ability to update code incrementally.
Our plan is therefore to do a short series of quick releases:
- deprecation warnings are off: users can opt-in (v.8.7.0)
- deprecation warnings are on: users can opt-out (v.8.9.1)
- deprecation warnings are forced, code still exists
- the deprecated methods are hidden: users can opt-in
- the deprecated methods are removed
| Step | Deprecation Warnings | Deprecated Code |
|---|---|---|
See APPROVAL_TESTS_SHOW_DEPRECATION_WARNINGS |
See APPROVAL_TESTS_HIDE_DEPRECATED_CODE |
|
| 1 | Optional: off | Optional: enabled |
| 2 | Optional: on | Optional: enabled |
| 3 | Always on | Optional: enabled |
| 4 | Always on | Optional: hidden |
| 5 | Not applicable | Removed |
We suggest that any time you want to remove the deprecations, you jump ahead and toggle hide-deprecations, and let the compiler help you find the code you need to update.
Currently (2020-04-21), deprecation warnings are turned off by default.
To change that, see How to Toggle Enabling or Disabling of Deprecated Code.
Whenever we deprecate a method, the implementation of the deprecated method will always contain a single line, which is how we want the code to be called in the future.
As such, you can always open up the method to see how to convert your code.
If you IDE supports inlining, you can also select your old function call, and inline just that one line, and your IDE will update the code for you.
Note If you are reading this after we have removed the deprecated methods, please download a slightly earlier release, and then follow one of the steps above.
Instead of passing in a Reporter instance, you are now going to pass in an Options object containing the Reporter instance, for example Options(MyReporter()).
This is an example what the new code would look like:
Approvals::verify("text to be verified", Options(Windows::AraxisMergeReporter()));Before, we had several overloads of a special method - verifyWithExtension() - to set the file extension to be used when verifying a piece of text, for when .txt was not appropriate.
Because Options allows the file extension to be specified, all verify methods now have this capability.
As such, this specialised method is redundant, and is being removed.
This is an example what the new code would look like:
Approvals::verify("<h1>hello world</h1>",
Options().fileOptions().withFileExtension(".html"));