Criar e testar PowerShell

Introdução

Este guia mostra como usar PowerShell para CI. Ele descreve como usar o Pester, instalar dependências, testar seu módulo e publicar na Galeria do PowerShell.

Executores hospedados em GitHub têm um cache de ferramentas com software pré-instalado que inclui PowerShell e Pester.

Para ver a lista completa de softwares atualizados e as versões pré-instaladas do PowerShell and Pester, confira Executores hospedados no GitHub.

Pré-requisitos

Você deve estar familiarizado com o YAML e a sintaxe do GitHub Actions. Para saber mais, confira Escrevendo fluxos de trabalho.

Recomendamos que você tenha um entendimento básico de PowerShell e Pester. Para obter mais informações, consulte:

• Introdução ao PowerShell
• Pester

Adicionar um fluxo de trabalho ao Pester

Para automatizar o seu teste com PowerShell e Pester, você pode adicionar um fluxo de trabalho que é executado toda vez que uma alteração é carregada no seu repositório. No exemplo a seguir, Test-Path é usado para verificar se um arquivo chamado resultsfile.log está presente.

Este exemplo de arquivo de fluxo de trabalho precisa ser adicionado ao diretório .github/workflows/ do repositório:

name: Test PowerShell on Ubuntu on: push jobs: pester-test: name: Pester test runs-on: ubuntu-latest steps: - name: Check out repository code uses: actions/checkout@v5 - name: Perform a Pester test from the command-line shell: pwsh run: Test-Path resultsfile.log | Should -Be $true - name: Perform a Pester test from the Tests.ps1 file shell: pwsh run: | Invoke-Pester Unit.Tests.ps1 -Passthru 

• shell: pwsh – Configura o trabalho para usar o PowerShell ao executar os comandos run.

• run: Test-Path resultsfile.log – Verifique se um arquivo chamado resultsfile.log está presente no diretório raiz do repositório.

• Should -Be $true – Usa o Pester para definir um resultado esperado. Se o resultado for inesperado, GitHub Actions irá sinalizar isso como um teste falho. Por exemplo:

  

• Invoke-Pester Unit.Tests.ps1 -Passthru – Usa o Pester para executar testes definidos em um arquivo chamado Unit.Tests.ps1. Por exemplo, para executar o mesmo teste descrito acima, o Unit.Tests.ps1 conterá o seguinte:

  Describe "Check results file is present" { It "Check results file is present" { Test-Path resultsfile.log | Should -Be $true } } 

Locais de módulos do PowerShell

A tabela abaixo descreve os locais para diversos módulos do PowerShell em cada executor hospedado em GitHub.

Instalar dependências

Executores hospedados em GitHub têm PowerShell 7 e o Pester instalado. Use Install-Module para instalar dependências adicionais da Galeria do PowerShell antes de compilar e testar seu código.

Você também pode armazenar dependências em cache para acelerar seu fluxo de trabalho. Para saber mais, confira Referência do cache de dependência.

Por exemplo, o seguinte trabalho instala os módulos SqlServer e PSScriptAnalyzer:

jobs: install-dependencies: name: Install dependencies runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Install from PSGallery shell: pwsh run: | Set-PSRepository PSGallery -InstallationPolicy Trusted Install-Module SqlServer, PSScriptAnalyzer 

Memorizar dependências

Você pode armazenar as dependências do PowerShell em cache usando uma chave exclusiva, o que permite restaurar as dependências em fluxos de trabalho futuros com a ação cache. Para saber mais, confira Referência do cache de dependência.

O PowerShell armazena suas dependências em diferentes locais, dependendo do sistema operacional do executor. Por exemplo, o local de path usado no exemplo do Ubuntu a seguir será diferente para um sistema operacional Windows.

steps: - uses: actions/checkout@v5 - name: Setup PowerShell module cache id: cacher uses: actions/cache@v4 with: path: "~/.local/share/powershell/Modules" key: ${{ runner.os }}-SqlServer-PSScriptAnalyzer - name: Install required PowerShell modules if: steps.cacher.outputs.cache-hit != 'true' shell: pwsh run: | Set-PSRepository PSGallery -InstallationPolicy Trusted Install-Module SqlServer, PSScriptAnalyzer -ErrorAction Stop 

Testar seu código

Você pode usar os mesmos comandos usados localmente para criar e testar seu código.

Usar PSScriptAnalyzer para código lint

O exemplo a seguir instala PSScriptAnalyzer e o usa para fazer lint de todos os arquivos ps1 no repositório. Para obter mais informações, confira PSScriptAnalyzer no GitHub.

 lint-with-PSScriptAnalyzer: name: Install and run PSScriptAnalyzer runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Install PSScriptAnalyzer module shell: pwsh run: | Set-PSRepository PSGallery -InstallationPolicy Trusted Install-Module PSScriptAnalyzer -ErrorAction Stop  - name: Lint with PSScriptAnalyzer shell: pwsh run: | Invoke-ScriptAnalyzer -Path *.ps1 -Recurse -Outvariable issues $errors = $issues.Where({$_.Severity -eq 'Error'}) $warnings = $issues.Where({$_.Severity -eq 'Warning'}) if ($errors) { Write-Error "There were $($errors.Count) errors and $($warnings.Count) warnings total." -ErrorAction Stop } else { Write-Output "There were $($errors.Count) errors and $($warnings.Count) warnings total." } 

Empacotar dados do fluxo de trabalho como artefatos

Você pode fazer o upload de artefatos para visualização após a conclusão de um fluxo de trabalho. Por exemplo, é possível que você precise salvar os arquivos de registro, os despejos de núcleo, os resultados de teste ou capturas de tela. Para saber mais, confira Armazenar e compartilhar dados com artefatos de fluxo de trabalho.

O exemplo a seguir demonstra como usar a ação upload-artifact para arquivar os resultados do teste recebidos de Invoke-Pester. Para obter mais informações, confira a ação upload-artifact.

name: Upload artifact from Ubuntu on: [push] jobs: upload-pester-results: name: Run Pester and upload results runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Test with Pester shell: pwsh run: Invoke-Pester Unit.Tests.ps1 -Passthru | Export-CliXml -Path Unit.Tests.xml - name: Upload test results uses: actions/upload-artifact@v4 with: name: ubuntu-Unit-Tests path: Unit.Tests.xml if: ${{ always() }} 

A função always() configura o trabalho para continuar o processamento mesmo se houver falhas de teste. Para saber mais, confira Referência de contextos.

Publicar na Galeria do PowerShell

Você pode configurar o seu fluxo de trabalho para publicar o seu módulo do PowerShell para a Galeria PowerShell quando o seu teste de passar. Você pode usar segredos para armazenar quaisquer tokens ou credenciais necessárias para publicar seu pacote. Para saber mais, confira Usar segredos em ações do GitHub.

O seguinte exemplo cria um pacote e usa Publish-Module para publicá-lo na Galeria do PowerShell:

name: Publish PowerShell Module on: release: types: [created] jobs: publish-to-gallery: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Build and publish env: NUGET_KEY: ${{ secrets.NUGET_KEY }} shell: pwsh run: | ./build.ps1 -Path /tmp/samplemodule Publish-Module -Path /tmp/samplemodule -NuGetApiKey $env:NUGET_KEY -Verbose