Skip to main content

Enterprise Server 3.23 は、現在リリース候補として使用できます。

Skip to content

PowerShell のビルドとテスト

PowerShell プロジェクトのビルドとテストのための継続的インテグレーション (CI) ワークフローを作成する方法について説明します。

メモ

GitHub ホステッド ランナーは、現在 GitHub Enterprise Server ではサポートされていません。

はじめに

このガイドでは、CIのためのPowerShellの使用方法を示します。 Pester の使用方法、依存関係のインストール方法、モジュールのテスト方法、PowerShell ギャラリーへの発行方法について説明します。

GitHubホストされているランナーには、PowerShell と Pester を含む、プレインストールされたソフトウェアを含むツール キャッシュがあります。

最新のソフトウェアと、PowerShell および Pester のプレインストールされたバージョンの完全なリストについては、「GitHub ホステッド ランナー」を参照してください。

前提条件

YAML と 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@v6
      - 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 - run コマンドを実行するときに PowerShell を使うようにジョブを構成します。

  • 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のモジュールの場所

次の表では、各 GitHubホストランナーにおけるさまざまな PowerShell モジュールの場所について説明します。

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 モジュールは、PowerShell アドオン モジュールの既定の場所 (つまり、/usr/share/) ではなく、/usr/local/share/powershell/Modules/ に格納されます。

依存関係のインストール

GitHubホストされているランナーには、PowerShell 7 と Pester がインストールされています。 Install-Module を使用して、コードをビルドしてテストする前に、PowerShell ギャラリーから追加の依存関係をインストールできます。

メモ

GitHubホストランナーによって使用されるプレインストール済みパッケージ (Pester など) は定期的に更新され、大幅な変更が発生する可能性があります。 そのため、Install-Module で -MaximumVersion を使って必要なパッケージのバージョンを常に指定することをお勧めします。

ワークフローの速度を上げるために、依存関係をキャッシュすることもできます。 詳しくは、「依存関係キャッシュのリファレンス」をご覧ください。

たとえば、次のジョブでは、SqlServer モジュールと PSScriptAnalyzer モジュールがインストールされます。

jobs:
  install-dependencies:
    name: Install dependencies
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install from PSGallery
        shell: pwsh
        run: |
          Set-PSRepository PSGallery -InstallationPolicy Trusted
          Install-Module SqlServer, PSScriptAnalyzer

メモ

既定では、PowerShell によって信頼されるリポジトリはありません。 PowerShell ギャラリーからモジュールをインストールする場合は、PSGallery のインストール ポリシーを Trusted に明示的に設定する必要があります。

依存関係のキャッシング

一意のキーを使って PowerShell の依存関係をキャッシュすることができ、これにより将来のワークフローで cache アクションによってその依存関係を復元できます。 詳しくは、「依存関係キャッシュのリファレンス」をご覧ください。

PowerShellは、ランナーのオペレーティングシステムによって依存関係を様々な場所にキャッシュします。 たとえば、次の Ubuntu の例で使用する path の場所は、Windows オペレーティング システムでは異なります。

steps:
  - uses: actions/checkout@v6
  - 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 ファイルがリントされます。 詳細については、GitHub の「PSScriptAnalyzer」を参照してください。

  lint-with-PSScriptAnalyzer:
    name: Install and run PSScriptAnalyzer
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - 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@v6
      - 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() 関数では、テストにエラーがあっても処理を続行するようにジョブが構成されます。 詳しくは、「ワークフロー内とアクション内で式を評価する」をご覧ください。

CI テストに合格したときに PowerShell モジュールをPowerShell ギャラリーに発行するようにワークフローを構成できます。 パッケージを公開するのに必要なトークンや認証情報を保存するために、シークレットを使うことができます。 詳しくは、「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@v6
      - 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