V5 Documentation

Restrict ToString Usage To Avoid Side-Effects

Project-level NCrunch configuration setting Introduced NCrunch v5.0 Default Value: true
ID/Tag in config file: RestrictToString


NCrunch RDI collects data at run time by calling the ToString method on type instances. This provides a simple way to represent a type instance in the RDI overlay.

Although it is considered a convention in .NET that the ToString method should execute without side-effects, there is no guarantee of this. It is possible for a ToString method to change the state of the object implementing it, or perhaps perform a lazy-load of a related property. This can cause RDI to alter the behaviour of user code during execution, potentially causing tests to malfunction and fail, or provide false pass results.

To mitigate this problem, RDI performs static analysis of all types referenced by user code to identify types for which calling the ToString method may result in side-effects. Only type instances considered safe by this analysis will have their ToString results logged at run time. All other type instances will be written to the log using their type name only.

This setting controls RDI behaviour in regards to this situation. If the setting is 'False', RDI will consider all types to be safe and will call ToString for all non-null type instances.


For the overwhelming majority of codebases, it will be safe disable this setting. Doing so will give an improved experience when using RDI, as more useful data will be available.

The static analysis performed by RDI to identify side-effects could be considered extremely paranoid. Usually only the most simplistic ToString methods will be considered safe.

The recommended approach when first using RDI on an existing solution is to perform a full test run with this setting enabled. Once configuration has been tuned and all tests are passing, it is then suggested to try turning it off. If your code contains tests that are impacted by ToString side-effects, it may be better to use more finely targeted behaviour by tagging these tests with RestrictToStringAttribute.

Trial NCrunch
Take NCrunch for a spin
Do your fingers a favour and supercharge your testing workflow
Free Download