Rename [Mock] -Module to -FromModule, and deprecate -Module

[johndog]

... or -CallingModule, etc. The name "-Module" suggests that Mock needs to know which module is providing the function to be mocked, not which calling module needs to have the mock defined... the latter of these being the actuality.

Summary of the feature request

This was discussed in #462, and seems to be recurring stumbling block, as the purpose of -Module defies intuition. Every time I personally return to pester after some hiatus I wind up relearning the purpose of -Module.

How should it work? (optional)

Make -Module and -ModuleName aliases for compatibility, but make the new name the principle name.

[fflaten]

Sounds fair, but "-FromModule" would add to the confusion you'd like to solve. Maybe -InModule/AvailableInModule/PublishInModule?

However even with a better parameter-name, this topic is still pretty complicated and requires reading the manual before usage.

For example, I almost suggested -InModuleScope for consistency, but unlike InModuleScope MyModule { Mock .. } which affects the sessionstate of the ParameterFilter- and MockWith-scriptblocks, the Mock -ModuleName parameter only affects the hook placement.

So if this issue is fixed, a natural next step would be to introduce something like Mock -ExecuteInModule to set the sessionstate for MockWith and ParameterFilter-scriptblocks without requiring InModuleScope MyModule { Mock .. }.

[nohwnd]

I agree that the usage of -ModuleName is complicated, but I don't think just renaming it will solve the confusion.

[johndog]

A name that improves upon -ModuleName should have either of two outcomes:

• A. The dev might intuitively guess, correctly, the intent of the parameter.
• B. The dev might realize the parameter is too obtuse to guess about, and they need to revisit the manual.

The problem with "-ModuleName" is that it largely achieves neither of these; it leads to:

• C. A dev intuitively guesses, incorrectly, the intent of the parameter.

If "-FromModule" would lead to A for some and B for others, I don't see how it would add to the confusion... as long as it leads to less of C. Regardless, I'd be happier with any name that leads to either A or B with greater frequency, and I think that outcome would reduce confusion. -InModule or -WithinModule seem like they'd do the trick, too. -WithinModule is growing on me...

Eliminating the confusion needn't be a goal -- I can believe that the complexity is such that true understanding will typically require a read of the manual. A better name can help ensure that happens by at least making it harder to guess wrong about the behavior.