ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

PowerShell のビルドとテスト

PowerShell プロジェクトのビルドとテストのための継続的インテグレーション (CI) ワークフローを作成できます。

GitHub ActionsはGitHub Free、GitHub Pro、GitHub FreeのOrganization、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server、GitHub One、GitHub AEで利用できます。 GitHub Actionsは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。 詳しい情報については「GitHubの製品」を参照してください。

ここには以下の内容があります:

はじめに

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

GitHubホストランナーは、PowerShell及びPesterを含むプリインストールされたソフトウェアを伴うツールキャッシュを持ちます。

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

必要な環境

YAMLとGitHub Actionsの構文に馴染んでいる必要があります。 詳しい情報については、「GitHub Actions を学ぶ」を参照してください。

PowerShell及びPesterの基本的な理解をしておくことをおすすめします。 詳しい情報については、以下を参照してください。

Pesterのワークフローの追加

PowerShellとPesterでテストを自動化するには、変更がリポジトリにプッシュされるたびに実行されるワークフローを追加できます。 以下の例では、resultsfile.logというファイルがあるかをチェックするためにTest-Pathが使われます。

以下の例のワークフローファイルは、リポジトリの.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@v2
    - 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テスト

  • 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\*

依存関係のインストール

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

ノート: GitHubホストランナーが使用するプリインストールされたパッケージ(Pesterなど)は定期的に更新され、重要な変更が行われることがあります。 そのため、Install-Module-MaximumVersionを使って必要なパッケージのバージョンを常に指定しておくことをおすすめします。

GitHubホストランナーを使用する場合、依存関係をキャッシュしてワークフローの実行を高速化することもできます。 詳しい情報については、「ワークフローを高速化するための依存関係のキャッシュ」を参照してください。

たとえば以下のジョブは、SqlServer及びPSScriptAnalyzerモジュールをインストールします。

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

ノート: デフォルトでは、PowerShellはどのリポジトリも信頼しません。 PowerShell Galleryからモジュールをインストールする際には、PSGalleryのインストールポリシーを明示的にTrustedに設定しなければなりません。

依存関係のキャッシング

GitHub ホストランナーを使用する場合、一意のキーを使用してPowerShellの依存関係をキャッシュし、cacheアクションで将来のワークフローを実行するときに依存関係を復元できます。 詳しい情報については、「ワークフローを高速化するための依存関係のキャッシュ」を参照してください。

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

steps:
  - uses: actions/checkout@v2
  - name: Setup PowerShell module cache
    id: cacher
    uses: actions/cache@v2
    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@v2
    - 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@v2
    - 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@v2
      with:
        name: ubuntu-Unit-Tests
        path: Unit.Tests.xml
    if: ${{ always() }}

always()関数は、テストに失敗があっても継続するようにジョブを設定しています。 詳しい情報については「 always」を参照してください。

CIテストにパスしたら、PowerShellモジュールをPowerShell Galleryに公開するようにワークフローを設定できます。 パッケージを公開するのに必要なトークンや認証情報を保存するために、シークレットを使うことができます。 詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。

以下の例は、パッケージを作成し、Publish-Moduleを使ってそのパッケージをPowerShell Galleryに公開します。

name: Publish PowerShell Module

on:
  release:
    types: [created]

jobs:
  publish-to-gallery:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - 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

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

OR, learn how to contribute.