InModuleScope and LocalizationData Clarification

[PlagueHO]

@narrieta , @KarolKaczmarek - I just realized there is one other purpose to using InModuleScope in tests: It exposes variables defined by the Module to the tests. This is mostly used in existing tests to expose LocalizationData to the tests (e.g. to allow exact errors to be tested for).

Some modules also use other data declared by the Module as well (for example in xFirewall declares an array of properties that are exposed).

So, if this is required then InModuleScope either needs to be used or as an alternative the LocalizationData can be declared in the tests by the test itself.

This isn't going to be a problem as long as people know that they will need to either use InModuleScope OR declare the module variables in the tests as well.

I feel it is worth adding a note about this in the test templates. Thoughts?

[narrieta]

Yes, I agree it would be worth adding it. There will be parts of the test that need access to the module's private data and, as you point out, localization data is a great example of that.

Thanks!

[narrieta]

As a suggestion, one way to get a reference to private variables like localization data could be (in this example, $dscConfigurationLogBuffer is private to module AzureExtensionHandler):

Describe 'dscConfigurationLogBuffer' {
    $dscConfigurationLogBuffer = InModuleScope AzureExtensionHandler {
        $dscConfigurationLogBuffer
    }

    Context "When it is Cleared" {
       $dscConfigurationLogBuffer.Clear()
       It "Should have a count of 0 items" {
            $dscConfigurationLogBuffer._total | Should Be 0
        }
    }
}

This is very explicit about what part of the private data is being referenced in the tests and the rest of the code doesn't need to run in the scope of the module.

[KarolKaczmarek]

We shouldn't be using hardcoded error strings (whether localized or not) to test whether expected error occurred. Instead, please use FullyQualifiedErrorId

And while we may need some other private data from the module to create tests, this isn't most common scenario, so I don't think we should "pollute" test templates with info about it, I'd say test guidelines document would be a better place to add it.

[PlagueHO]

@KarolKaczmarek - most unit tests do a comparison on the entire error record (which contains FullyQualifiedErrorId) - for example: https://github.com/PowerShell/xWebAdministration/blob/dev/Tests/Unit/MSFT_xWebsite.Tests.ps1#L384

But the entire error record to compare also contains the localized error message, so it is required to be accessible from inside the unit test. I'm not sure if this can be changed either as it is part of the Pester "Should Throw $errorRecord" code - so the error record comparison is performed by Pester.

Anyway, I don't see this as a massive problem. Some resources don't throw any custom errors or specifically test them (they should but don't) - so this is only required if the resource tests custom errors. If that is the case then @narrieta 's solution would work nicely I think. As long as people are told what they should do then I don't see too much of a problem :)

[KarolKaczmarek]

yup, I agree