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 "Usar executores hospedados no GitHub".

Pré-requisitos

Você deve estar familiarizado com o YAML e a sintaxe do GitHub Actions. Para obter mais informações, 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 obter mais informações, 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@v4
      - 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 obter mais informações, confira "Memorizar dependências para acelerar os fluxos de trabalho".

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@v4
      - 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 obter mais informações, confira "Memorizar dependências para acelerar os fluxos de trabalho".

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@v4
  - name: Setup PowerShell module cache
    id: cacher
    uses: actions/cache@v3
    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@v4
      - 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 obter mais informações, confira "Armazenando e compartilhando dados de um 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@v4
      - 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 obter mais informações, confira "Acessar informações contextuais sobre execuções de fluxo de trabalho".

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 obter mais informações, 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@v4
      - 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