Примечание. В GitHub Enterprise Server в настоящее время не поддерживаются средства выполнения тестов, размещенные в GitHub. Дополнительные сведения о планируемой поддержке в будущем см. в GitHub public roadmap.
Введение
В этом руководстве описано использование PowerShell для CI. Здесь описано, как использовать Pester, устанавливать зависимости, тестировать модуль и выполнять публикацию в коллекции PowerShell.
Размещенные в GitHub средства выполнения имеют кэш инструментов с предварительно установленным программным обеспечением, включающим в себя PowerShell и Pester.
Полный список актуального программного обеспечения и предварительно установленных версий PowerShell и Pester см. в разделе "Использование средств выполнения, размещенных в GitHub".
Необходимые компоненты
Требуются знания YAML и синтаксиса GitHub Actions. Дополнительные сведения см. в разделе Изучение GitHub Actions.
Рекомендуется иметь базовое представление о 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 средстве выполнения.
Ubuntu | macOS | Windows | |
---|---|---|---|
Системные модули 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@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