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

Введение

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

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

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

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

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

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

• Начало работы с PowerShell
• Pester

Использование локальных средств выполнения тестов для GitHub Enterprise Server

При использовании действий установки (таких как actions/setup-LANGUAGE) в GitHub Enterprise Server с использованием локальных средств выполнения тестов может потребоваться настроить в них кэш инструментов, у которых отсутствует доступ к Интернету. Дополнительные сведения см. в разделе Настройка кэша инструментов для локально размещенных средств выполнения без доступа к Интернету.

Добавление рабочего процесса для 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 помечает этот тест как неудачный. Например:

  

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

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

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

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

Например, следующее задание устанавливает модули 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 можно кэшировать с помощью уникального ключа, что позволяет восстановить зависимости для будущих рабочих процессов посредством действия 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@v3
        with:
          name: ubuntu-Unit-Tests
          path: Unit.Tests.xml
    if: ${{ always() }}

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

Публикация в коллекции PowerShell

Вы можете настроить рабочий процесс для публикации модуля 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