Skip to main content

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

Вы можете создать рабочий процесс непрерывной интеграции для сборки и тестирования проекта PowerShell.

Введение

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

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

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

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

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

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

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

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

    Снимок экрана: сбой запуска рабочего процесса для теста Pester. Тестовые отчеты "Ожидаемые $true, но получили $false" и "Ошибка: обработка завершена с кодом выхода 1".

  • 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 средстве выполнения.

UbuntumacOSWindows
Системные модули PowerShell/opt/microsoft/powershell/7/Modules/*/usr/local/microsoft/powershell/7/Modules/*C:\program files\powershell\7\Modules\*
Модули надстроек PowerShell/usr/local/share/powershell/Modules/*/usr/local/share/powershell/Modules/*C:\Modules\*
Устанавливаемые пользователем модули/home/runner/.local/share/powershell/Modules/*/Users/runner/.local/share/powershell/Modules/*C:\Users\runneradmin\Documents\PowerShell\Modules\*

Примечание. В модулях Запуска Ubuntu модули Azure PowerShell хранятся /usr/share/ вместо расположения модулей надстроек PowerShell по умолчанию (т. е. /usr/local/share/powershell/Modules/).

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

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

Примечание. Предварительно установленные пакеты (например, Pester), используемые размещенными в GitHub средствами выполнения, регулярно обновляются и могут вносить существенные изменения. Поэтому рекомендуется всегда указывать необходимые версии пакетов, используя Install-Module с -MaximumVersion.

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

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

Примечание. По умолчанию никакие репозитории не являются доверенными для PowerShell. При установке модулей из коллекции PowerShell необходимо явно задать для политики установки PSGallery значение Trusted.

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

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

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

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

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

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

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

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

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

В следующем примере показано, как использовать действие 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@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@v4
        with:
          name: ubuntu-Unit-Tests
          path: Unit.Tests.xml
    if: ${{ always() }}

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

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

В следующем примере создается пакет, и используется Publish-Module для его публикации в коллекции 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