Currently the docstring for with-redefs recommends itself for use in testing. However there are a number of reasons why using this macro for testing is suboptimal:
with-redefs "bindings" are not transferred to new threads since it's a global mutation- users can get runtime errors if they redef a primitive type-hinted function to a function taking only objects
- If parts of the body of
with-redefs is delayed (via a delay, go block, etc.) that code may not see the new root
- The mutation is global so it "leaks" outside the current scope into other code that may currently be running in another thread
- Clojure tends to shun global mutation, and yet this macro isn't marked with a
! nor properly warns users about the dangers mentioned here
Due to these reasons I often encounter new users using with-redefs without understanding the ramifications of doing so. All this behavior makes sense if a user understands how Vars work, but that's a lot of knowledge to take on for a new user.
Suggestion:
Remove the suggestion that with-redefs be used in testing
Add a few notes of warning about global mutation, and concurrency issues with the macro.
