Skip to main content

Criar e testar PowerShell

É possível criar um fluxo de trabalho de integração contínua (CI) para criar e testar o seu projeto de PowerShell.

Observação: no momento, não há suporte para os executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.

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:

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:

    Captura de tela de uma falha de execução de fluxo de trabalho para um teste do Pester. Relatórios de teste "Esperado $true, mas obtido $false" e "Erro: processo concluído com o código de saída 1".

  • 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.

UbuntumacOSWindows
Módulos do sistema do PowerShell/opt/microsoft/powershell/7/Modules/*/usr/local/microsoft/powershell/7/Modules/*C:\program files\powershell\7\Modules\*
Módulos de complementos do PowerShell/usr/local/share/powershell/Modules/*/usr/local/share/powershell/Modules/*C:\Modules\*
Módulos instalados pelo usuário/home/runner/.local/share/powershell/Modules/*/Users/runner/.local/share/powershell/Modules/*C:\Users\runneradmin\Documents\PowerShell\Modules\*

Observação: em executores do Ubuntu, os módulos do Azure PowerShell são armazenados em /usr/share/ em vez de no local padrão dos módulos complementares do PowerShell (ou seja, /usr/local/share/powershell/Modules/).

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.

Observação: os pacotes pré-instalados (como o Pester) usados pelos executores hospedados no GitHub são atualizados regularmente e podem introduzir alterações significativas. Como resultado, recomendamos que você sempre especifique as versões de pacote necessárias usando Install-Module com -MaximumVersion.

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

Observação: por padrão, nenhum repositório é confiável pelo PowerShell. Ao instalar módulos da Galeria do PowerShell, você precisa definir explicitamente a política de instalação de PSGallery como Trusted.

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".

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