Создание и тестирование для PowerShell

Введение

В этом руководстве описано использование PowerShell для CI. В нём описывается, как использовать Pester, устанавливать зависимости, тестировать модуль и публиковать в PowerShell Gallery.

Размещенные в GitHub средства выполнения имеют кэш инструментов с предварительно установленным программным обеспечением, включающим в себя PowerShell и Pester.

Полный список актуального программного обеспечения и предварительно установленных версий PowerShell и Pester см. в разделе Средства выполнения тестов, размещенные в GitHub.

Необходимые компоненты

Требуются знания YAML и синтаксиса GitHub Actions. Дополнительные сведения см. в разделе Написание рабочих процессов.

Рекомендуется иметь базовое представление о PowerShell и Pester. Дополнительные сведения см. в разделе: * Начало работы с PowerShell * Pester

Добавление рабочего процесса для Pester

Чтобы автоматизировать тестирование с помощью PowerShell и Pester, можно добавить рабочий процесс, который запускается при каждой отправке изменения в репозиторий. В следующем примере Test-Path используется для проверки наличия файла resultsfile.log.

Этот пример файла рабочего процесса необходимо добавить в каталог .github/workflows/ репозитория:

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` — настраивает задание для использования PowerShell при выполнении команд `run`.
  

•         `run: Test-Path resultsfile.log` — проверяет, присутствует ли файл `resultsfile.log` в корневом каталоге репозитория.
  

•         `Should -Be $true` — использует Pester для определения ожидаемого результата. Если получен непредвиденный результат, GitHub Actions помечает этот тест как неудачный. Например:
  

  

•         `Invoke-Pester Unit.Tests.ps1 -Passthru` — использует Pester для выполнения тестов, определенных в файле `Unit.Tests.ps1`. Например, чтобы выполнить тест, аналогичны описанному выше, `Unit.Tests.ps1` будет содержать следующее:
  

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

Расположения модулей PowerShell

В приведенной ниже таблице описаны расположения расположений для разных модулей PowerShell в каждом размещенном в GitHub средстве выполнения.

          **Системные модули PowerShell** |`/opt/microsoft/powershell/7/Modules/*`|`/usr/local/microsoft/powershell/7/Modules/*`|`C:\program files\powershell\7\Modules\*`|

Установка зависимостей

Для размещенных в GitHub средств выполнения установлены PowerShell 7 и Pester. Вы можете использовать Install-Module для установки дополнительных зависимостей из PowerShell Gallery перед сборкой и тестированием кода.

Можно также кэшировать зависимости, чтобы ускорить рабочий процесс. Дополнительные сведения см. в разделе Справочник по кэшированию зависимостей.

Например, следующее задание устанавливает модули SqlServer и 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

Кэширование зависимостей

Зависимости PowerShell можно кэшировать с помощью уникального ключа, что позволяет восстановить зависимости для будущих рабочих процессов посредством действия cache. Дополнительные сведения см. в разделе Справочник по кэшированию зависимостей.

PowerShell кэширует свои зависимости в разных расположениях в зависимости от операционной системы средства выполнения. Например, местоположение path, используемое в следующем примере Ubuntu, будет отличаться для операционной системы 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

Тестирование кода

Вы можете использовать те же команды, которые используются для создания и тестирования кода в локальной среде.

Использование PSScriptAnalyzer для анализа кода

В следующем примере выполняется установка PSScriptAnalyzer и его использование для анализа кода всех файлов ps1 в репозитории. Для получения дополнительной информации см. PSScriptAnalyzer на 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."
          }

Упаковка данных рабочего процесса в виде артефактов

Вы можете отправить артефакты для просмотра после завершения рабочего процесса. Например, может потребоваться сохранить файлы журналов, основные дампы, результаты теста или снимки экрана. Дополнительные сведения см. в разделе Хранение и предоставление общего доступа к данным с артефактами рабочего процесса.

В следующем примере показано, как использовать действие upload-artifact для архивации результатов теста, полученных из Invoke-Pester. Дополнительные сведения см. в описании действия 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() }}

Функция always() настраивает задание для продолжения обработки даже при наличии сбоев тестов. Дополнительные сведения см. в разделе Справочник по контекстам.

Публикация для PowerShell Gallery

Вы можете настроить рабочий процесс так, чтобы публиковать модуль PowerShell в PowerShell Gallery после прохождения тестов CI. Вы можете использовать секреты для хранения любых маркеров или учетных данных, необходимых для публикации пакета. Дополнительные сведения см. в разделе Использование секретов в GitHub Actions.

Следующий пример создаёт пакет и использует Publish-Module для публикации в PowerShell Gallery:

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