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

Usar executores auto-hospedados no GitHub Enterprise Server

Ao usar ações de instalação (como actions/setup-LANGUAGE) no GitHub Enterprise Server com executores auto-hospedados, talvez seja necessário configurar o cache de ferramentas nos executores que não têm acesso à Internet. Para saber mais, confira Configurar o cache de ferramentas em executores auto-hospedados sem acesso à internet.

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@v3
        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