{"meta":{"title":"Criar e testar PowerShell","intro":"Saiba como criar um fluxo de trabalho de integração contínua (CI) para criar e testar seu projeto do PowerShell.","product":"GitHub Actions","breadcrumbs":[{"href":"/pt/enterprise-server@3.16/actions","title":"GitHub Actions"},{"href":"/pt/enterprise-server@3.16/actions/tutorials","title":"Tutoriais"},{"href":"/pt/enterprise-server@3.16/actions/tutorials/build-and-test-code","title":"Criar e testar código"},{"href":"/pt/enterprise-server@3.16/actions/tutorials/build-and-test-code/powershell","title":"PowerShell"}],"documentType":"article"},"body":"# Criar e testar PowerShell\n\nSaiba como criar um fluxo de trabalho de integração contínua (CI) para criar e testar seu projeto do PowerShell.\n\n> \\[!NOTE]\n> No momento, não há suporte para executores hospedados no GitHub Enterprise Server no GitHub.\n\n## Introdução\n\nEste guia mostra como usar PowerShell para CI. Ele descreve como usar o Pester, instalar dependências, testar seu módulo e publicar no PowerShell Gallery.\n\nExecutores hospedados em GitHub têm um cache de ferramentas com software pré-instalado que inclui PowerShell e Pester.\n\nPara ver a lista completa de softwares atualizados e as versões pré-instaladas do PowerShell and Pester, confira [Executores hospedados no GitHub](/pt/enterprise-server@3.16/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software).\n\n## Pré-requisitos\n\nVocê deve estar familiarizado com o YAML e a sintaxe do GitHub Actions. Para saber mais, confira [Escrevendo fluxos de trabalho](/pt/enterprise-server@3.16/actions/learn-github-actions).\n\nRecomendamos que você tenha um entendimento básico de PowerShell e Pester. Para obter mais informações, consulte:\n\n* [Introdução ao PowerShell](https://docs.microsoft.com/powershell/scripting/learn/ps101/01-getting-started)\n* [Pester](https://pester.dev)\n\n### Usar executores auto-hospedados no GitHub Enterprise Server\n\nAo 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](/pt/enterprise-server@3.16/admin/github-actions/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access).\n\n## Adicionar um fluxo de trabalho ao Pester\n\nPara 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.\n\nEste exemplo de arquivo de fluxo de trabalho precisa ser adicionado ao diretório `.github/workflows/` do repositório:\n\n```yaml\nname: Test PowerShell on Ubuntu\non: push\n\njobs:\n  pester-test:\n    name: Pester test\n    runs-on: ubuntu-latest\n    steps:\n      - name: Check out repository code\n        uses: actions/checkout@v6\n      - name: Perform a Pester test from the command-line\n        shell: pwsh\n        run: Test-Path resultsfile.log | Should -Be $true\n      - name: Perform a Pester test from the Tests.ps1 file\n        shell: pwsh\n        run: |\n          Invoke-Pester Unit.Tests.ps1 -Passthru\n```\n\n* `shell: pwsh` – Configura o trabalho para usar o PowerShell ao executar os comandos `run`.\n\n* `run: Test-Path resultsfile.log` – Verifique se um arquivo chamado `resultsfile.log` está presente no diretório raiz do repositório.\n\n* `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:\n\n  ![Captura de tela de uma falha na execução do fluxo de trabalho para um teste do Pester. Relatórios de testes dizem: \"Esperava-se $true, mas foi obtido $false\" e \"Erro: o processo foi concluído com o código de saída 1.\"](/assets/images/help/repository/actions-failed-pester-test-updated.png)\n\n* `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:\n\n  ```powershell\n  Describe \"Check results file is present\" {\n      It \"Check results file is present\" {\n          Test-Path resultsfile.log | Should -Be $true\n      }\n  }\n  ```\n\n## Locais de módulos do PowerShell\n\nA tabela abaixo descreve os locais de diversos módulos do PowerShell em cada runner hospedado em GitHub.\n\n<div class=\"ghd-tool rowheaders\">\n\n|                                           | Ubuntu                                           | macOS                                             | Windows                                               |\n| ----------------------------------------- | ------------------------------------------------ | ------------------------------------------------- | ----------------------------------------------------- |\n| **Módulos do sistema do PowerShell**      | `/opt/microsoft/powershell/7/Modules/*`          | `/usr/local/microsoft/powershell/7/Modules/*`     | `C:\\program files\\powershell\\7\\Modules\\*`             |\n| **Módulos de complementos do PowerShell** | `/usr/local/share/powershell/Modules/*`          | `/usr/local/share/powershell/Modules/*`           | `C:\\Modules\\*`                                        |\n| **Módulos instalados pelo usuário**       | `/home/runner/.local/share/powershell/Modules/*` | `/Users/runner/.local/share/powershell/Modules/*` | `C:\\Users\\runneradmin\\Documents\\PowerShell\\Modules\\*` |\n\n</div>\n\n> \\[!NOTE]\n> Nos runners do Ubuntu, os módulos Azure PowerShell são armazenados em `/usr/share/` em vez do local padrão dos módulos complementares do PowerShell (ou seja, `/usr/local/share/powershell/Modules/`).\n\n## Instalar dependências\n\nExecutores hospedados em GitHub têm PowerShell 7 e o Pester instalado. Você pode usar `Install-Module` para instalar dependências adicionais do PowerShell Gallery antes de compilar e testar seu código.\n\n> \\[!NOTE]\n> 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`.\n\nVocê 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](/pt/enterprise-server@3.16/actions/using-workflows/caching-dependencies-to-speed-up-workflows).\n\nPor exemplo, o seguinte trabalho instala os módulos `SqlServer` e `PSScriptAnalyzer`:\n\n```yaml\njobs:\n  install-dependencies:\n    name: Install dependencies\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Install from PSGallery\n        shell: pwsh\n        run: |\n          Set-PSRepository PSGallery -InstallationPolicy Trusted\n          Install-Module SqlServer, PSScriptAnalyzer\n```\n\n> \\[!NOTE]\n> Por padrão, nenhum repositório é confiável pelo PowerShell. Ao instalar módulos do PowerShell Gallery, você deve definir explicitamente a política de instalação para `PSGallery` para `Trusted`.\n\n### Memorizar dependências\n\nVocê 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`](https://github.com/marketplace/actions/cache). Para saber mais, confira [Referência do cache de dependência](/pt/enterprise-server@3.16/actions/using-workflows/caching-dependencies-to-speed-up-workflows).\n\nO PowerShell armazena suas dependências em diferentes locais, dependendo do sistema operacional do executor. Por exemplo, a `path` localização usada no exemplo do Ubuntu a seguir será diferente em um sistema operacional Windows.\n\n```yaml\nsteps:\n  - uses: actions/checkout@v6\n  - name: Setup PowerShell module cache\n    id: cacher\n    uses: actions/cache@v4\n    with:\n      path: \"~/.local/share/powershell/Modules\"\n      key: ${{ runner.os }}-SqlServer-PSScriptAnalyzer\n  - name: Install required PowerShell modules\n    if: steps.cacher.outputs.cache-hit != 'true'\n    shell: pwsh\n    run: |\n      Set-PSRepository PSGallery -InstallationPolicy Trusted\n      Install-Module SqlServer, PSScriptAnalyzer -ErrorAction Stop\n```\n\n## Testar seu código\n\nVocê pode usar os mesmos comandos usados localmente para criar e testar seu código.\n\n### Usar o PSScriptAnalyzer para verificar código\n\nO exemplo a seguir instala `PSScriptAnalyzer` e o usa para fazer lint de todos os arquivos `ps1` no repositório. Para obter mais informações, consulte [PSScriptAnalyzer no GitHub](https://github.com/PowerShell/PSScriptAnalyzer).\n\n```yaml\n  lint-with-PSScriptAnalyzer:\n    name: Install and run PSScriptAnalyzer\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Install PSScriptAnalyzer module\n        shell: pwsh\n        run: |\n          Set-PSRepository PSGallery -InstallationPolicy Trusted\n          Install-Module PSScriptAnalyzer -ErrorAction Stop\n      - name: Lint with PSScriptAnalyzer\n        shell: pwsh\n        run: |\n          Invoke-ScriptAnalyzer -Path *.ps1 -Recurse -Outvariable issues\n          $errors   = $issues.Where({$_.Severity -eq 'Error'})\n          $warnings = $issues.Where({$_.Severity -eq 'Warning'})\n          if ($errors) {\n              Write-Error \"There were $($errors.Count) errors and $($warnings.Count) warnings total.\" -ErrorAction Stop\n          } else {\n              Write-Output \"There were $($errors.Count) errors and $($warnings.Count) warnings total.\"\n          }\n```\n\n## Empacotar dados do fluxo de trabalho como artefatos\n\nVocê 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](/pt/enterprise-server@3.16/actions/using-workflows/storing-workflow-data-as-artifacts).\n\nO 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`](https://github.com/actions/upload-artifact).\n\n```yaml\nname: Upload artifact from Ubuntu\n\non: [push]\n\njobs:\n  upload-pester-results:\n    name: Run Pester and upload results\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Test with Pester\n        shell: pwsh\n        run: Invoke-Pester Unit.Tests.ps1 -Passthru | Export-CliXml -Path Unit.Tests.xml\n      - name: Upload test results\n        uses: actions/upload-artifact@v3\n        with:\n          name: ubuntu-Unit-Tests\n          path: Unit.Tests.xml\n    if: ${{ always() }}\n```\n\nA função `always()` configura o trabalho para continuar o processamento mesmo se houver falhas de teste. Para saber mais, confira [Referência de contextos](/pt/enterprise-server@3.16/actions/learn-github-actions/contexts#always).\n\n## Publicando no PowerShell Gallery\n\nVocê pode configurar seu fluxo de trabalho para publicar o módulo do PowerShell no PowerShell Gallery quando os testes de CI forem aprovados. 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](/pt/enterprise-server@3.16/actions/security-guides/using-secrets-in-github-actions).\n\nO exemplo a seguir cria um pacote e usa `Publish-Module` para publicá-lo no PowerShell Gallery:\n\n```yaml\nname: Publish PowerShell Module\n\non:\n  release:\n    types: [created]\n\njobs:\n  publish-to-gallery:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Build and publish\n        env:\n          NUGET_KEY: ${{ secrets.NUGET_KEY }}\n        shell: pwsh\n        run: |\n          ./build.ps1 -Path /tmp/samplemodule\n          Publish-Module -Path /tmp/samplemodule -NuGetApiKey $env:NUGET_KEY -Verbose\n```"}