04 / SHIP DEPENDABLE FLEET TOOLS · LESSON 15

Test the scanner contract with Pester

Write tests that accept the working scanner and expose timeout and missing-result regressions.

20 min · learn at your pace

Test behaviour at the adapter boundary

A fake probe is a small script block that returns a deterministic object. It can echo the timeout, throw for one endpoint, or return an Open observation without opening any socket. This makes scanner tests fast and repeatable.

Write a Pester file with BeforeAll dot-sourcing ScannerCandidate.ps1. Keep all three It blocks inside Describe. The supplied candidate contains Get-ScanPlan and Invoke-PortScan; your suite should test their public behaviour, not their source text.

Three useful checks

First, duplicate hostnames and duplicate ports must produce one result. Second, a caller-selected timeout such as 71 must reach the adapter unchanged. A fake probe can return that received value as ElapsedMs so you can assert it. Third, a thrown probe for one port must remain an Error row while a later port still produces a result.

The course runs your suite against a correct implementation and two faulty implementations: one silently substitutes the default timeout, and one drops failed endpoints. A suite that always passes, contains no assertions, or tests only the happy path cannot satisfy the exercise.

Separate the test author from the implementation

Save exactly three executable It blocks to Scanner.Tests.ps1. Do not modify ScannerCandidate.ps1. The outer course checks replace that candidate between runs and restore it afterward. This is a small example of testing whether your tests can detect a known behavioural regression. All candidates use fake probes and stay in the browser filesystem.

Go deeper

Read the official reference.

Try an example.ps1
Get-Content '/home/user/ScannerCandidate.ps1' -TotalCount 12
# Write assertions against Invoke-PortScan's public results.
YOUR TURN

Put it into practice.

Write /home/user/Scanner.Tests.ps1 with exactly three non-skipped It blocks: deduplicated pairs, forwarding a non-default timeout, and preserving a thrown-probe Error row while continuing to a later Open endpoint. Dot-source ScannerCandidate.ps1 in BeforeAll. The suite must pass the correct candidate and fail both supplied faulty behaviours.

See an explained solution
One way to solve it.ps1
$tests=@'
BeforeAll { . '/home/user/ScannerCandidate.ps1' }
Describe 'Scanner contract' {
    It 'deduplicates endpoint pairs' {
        $p={param($n,$p,$t) [pscustomobject]@{Status='Open';ElapsedMs=1;Detail='ok'}}
        @(Invoke-PortScan @('APP01','app01') @(443,443) @('app01') $p).Count | Should -Be 1
    }
    It 'forwards the caller timeout' {
        $p={param($n,$p,$t) [pscustomobject]@{Status='Open';ElapsedMs=$t;Detail='ok'}}
        (Invoke-PortScan @('app01') @(443) @('app01') $p 71).ElapsedMs | Should -Be 71
    }
    It 'keeps failed endpoints and continues' {
        $p={param($n,$p,$t) if($p -eq 22){throw 'broken'}; [pscustomobject]@{Status='Open';ElapsedMs=1;Detail='ok'}}
        $r=@(Invoke-PortScan @('app01') @(22,443) @('app01') $p)
        $r.Count | Should -Be 2
        ($r | Where-Object Port -EQ 22).Status | Should -Be Error
        ($r | Where-Object Port -EQ 443).Status | Should -Be Open
    }
}
'@
Set-Content '/home/user/Scanner.Tests.ps1' $tests

The suite tests the boundary rather than an implementation detail. The two faulty candidates demonstrate that your assertions can detect lost timeout arguments and incomplete coverage.