Extensibility docs should signpost & warn where developers could be caught out by cross-process marshalling

This relates to something that I have had this explained to me somewhere before, but it was years ago and I can't find where that discussion happened. I've looked through SO questions and issues/discussions on the NUnit repo.

There is a limitation, really a feature/consequence of NUnit's design (and not one I consider to be bad) In the default usage the "discovery and test suite/case creation" phase occurs at arms length to the "test execution" phase, I believe in a separate .NET process. From what I recall of the last time this was explained to me, objects/values which are created during discovery/creation are then marshalled in some manner over to the execution. Examples of this are where test case parameter values are injected by something which implements ITestBuilder.

When those objects turn up in the test case as a method parameters, they are not actually the precise same objects as were created in the test builder, because they have crossed a boundary (again, I think that's a process boundary). This can have some unexpected and baffling consequences to a developer if they had not had this boundary-crossing pointed out to them. For example, an object which emits events passed as a test case parameter. If an event listener is subscribed to that object over in the "discovery & creation" part of the test suite then events which are emitted during the test (triggered by logic that executes within the test) won't be observed by the subscriber. That's because the object emitting the events isn't actually the precise same object that was subscribed-to. The object emitting the events is a marshalled-copy of the original object.

I think the docs should point this out for extension points which can lead to this behaviour. It's not obvious if you are not already familiar with the deep internals of NUnit. Even having already been told once, over the course of a few years I managed to forget and was caught out by this a second time.

Start by locating the documentation for ITestBuilder and the discovery and test execution phases. Confirm where extension-point guidance belongs, then document the cross-process marshalling boundary and warn that values and event subscriptions created during discovery may not refer to the same objects during execution.