# バッチ設計書 8-gh-winactions.ps1

## 概要

本ドキュメントは、GitHub Actions用のWindows統合テストスクリプト「gh-winactions.ps1」の設計仕様を記載したものである。

### 本バッチの処理概要

本スクリプトは、GitHub ActionsのCI/CDパイプラインでWindows環境上のdbatoolsモジュールの統合テストを実行するPesterテストスクリプトである。PowerShell CoreとWindows PowerShell（Desktop）の両方に対応し、LocalDBまたはフルSQL Serverインスタンスを使用した接続テスト、DAC Package公開テスト、Azure SQL Database接続テストを実行する。

**業務上の目的・背景**：dbatoolsモジュールの主要なターゲット環境はWindowsであり、Windows上での動作を確実に保証する必要がある。特に、PowerShell CoreとWindows PowerShell（Desktop Edition）の両方での動作を検証することが重要である。本スクリプトは、GitHub ActionsのWindows runnerで実行され、LocalDB（軽量環境）またはフルSQL Server（完全環境）を使用してdbatoolsの主要機能をテストする。また、Azure SQL Databaseへの接続テストも実行し、クラウド環境との互換性を確認する。

**バッチの実行タイミング**：GitHub Actionsワークフローにより、プルリクエスト時やmainブランチへのプッシュ時に自動実行される。

**主要な処理内容**：
1. PowerShellエディション（Core/Desktop）に応じたテスト環境設定
2. LocalDBまたはフルSQL Serverへの接続設定
3. Publish-DbaDacPackageによるDAC Package公開テスト
4. Azure SQL Database接続テスト（Service Principal認証）
5. Azure接続文字列による接続テスト
6. Get-DbaDatabase によるAzureデータベース取得テスト

**前後の処理との関連**：GitHub Actionsワークフローにより、Windows runnerが準備される。LocalDB使用時は追加のセットアップは不要。フルSQL Server使用時は事前にインスタンスが起動されている必要がある。

**影響範囲**：CI/CDパイプラインの品質保証に影響する。テスト失敗時はプルリクエストのマージがブロックされる。

## バッチ種別

CI/CD / 統合テスト

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（PR/プッシュ時） |
| 実行時刻 | 該当なし |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | GitHub Actions（pull_request, push） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actions環境 | Windows runnerで実行 |
| PowerShell | Core または Desktop Edition |
| LocalDB または SQL Server | 接続可能なインスタンスが存在 |
| 環境変数 | CLIENTID, CLIENTSECRET, TENANTID等が設定済み |

### 実行可否判定

GitHub Actionsワークフローの条件に従う。テスト対象のタグ（IntegrationTests）で制御可能。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 環境変数およびPSVersionTableから自動取得 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| $PSVersionTable.PSEdition | 文字列 | PowerShellエディション（Core/Desktop） |
| 環境変数 CLIENTID | 文字列 | Azure Service Principal Client ID |
| 環境変数 CLIENTSECRET | 文字列 | Azure Service Principal Client Secret |
| 環境変数 TENANTID | 文字列 | Azure Tenant ID |
| 環境変数 CLIENT_GUID | 文字列 | 追加のAzure Client ID |
| 環境変数 CLIENT_GUID_SECRET | 文字列 | 追加のAzure Client Secret |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Pesterテスト結果 | コンソール出力 | テスト成功/失敗の詳細 |
| GitHub Actions | ステータス | ワークフローの成功/失敗 |

### 出力ファイル仕様

本スクリプトは直接ファイル出力を行わない。

## 処理フロー

### 処理シーケンス

```
1. BeforeAll: テスト環境セットアップ
   ├─ PowerShellエディションチェック
   ├─ Core: フルSQL Server接続設定（localhost, sa認証）
   └─ Desktop: LocalDB接続設定
2. PSDefaultParameterValuesの設定
   └─ SqlInstance, SqlCredential, Confirm等
3. dbatoolsモジュールのインポート
4. It "publishes a package": DAC Packageテスト
   ├─ テストデータベース作成
   ├─ テーブル・データ作成
   ├─ Export-DbaDacPackage実行
   ├─ データベース削除
   ├─ Publish-DbaDacPackage実行
   └─ 結果検証
5. It "connects to Azure using tenant and client id + client secret"
   └─ Connect-DbaInstance + Service Principal
6. It "connects to Azure using a query string"
   └─ Connect-DbaInstance + 接続文字列
7. It "gets a database from Azure"
   └─ Get-DbaDatabase
```

### フローチャート

```mermaid
flowchart TD
    A[テスト開始] --> B[BeforeAll: 環境セットアップ]
    B --> C{PSEdition?}
    C -->|Core| D[フルSQL Server設定]
    C -->|Desktop| E[LocalDB設定]
    D --> F[dbatoolsインポート]
    E --> F
    F --> G[DAC Packageテスト]
    G --> H[Azure接続テスト - Service Principal]
    H --> I[Azure接続テスト - 接続文字列]
    I --> J[Azureデータベース取得テスト]
    J --> K[テスト終了]
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DAC Packageテスト | dbo.example | CREATE TABLE, INSERT | テストデータ作成 |
| データベース作成・削除 | - | CREATE/DROP DATABASE | テスト用データベース管理 |

### テーブル別操作詳細

#### dbo.example（DAC Packageテスト用）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| CREATE TABLE | id | int PRIMARY KEY | テストテーブル |
| INSERT | id | top 100 object_id | sys.objectsから取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | テスト失敗 | Should条件を満たさない | Pesterがテスト失敗を報告 |
| - | 接続エラー | SQL Serverに接続できない | テスト失敗 |
| - | LocalDBエラー | LocalDBがサポートされていない（Core） | フルSQL Server使用 |
| - | Azure接続エラー | 認証情報が無効 | テスト失敗 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

テスト失敗時はGitHub Actionsワークフローが失敗ステータスになる。

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | テスト個別 |
| コミットタイミング | 各テスト終了時 |
| ロールバック条件 | テスト失敗時も明示的なロールバックなし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 4テストケース |
| 目標処理時間 | 5分以内 |
| メモリ使用量上限 | GitHub Actions runner制限内 |

## 排他制御

GitHub Actionsにより同一PRへの同時実行は制限される。テスト用データベース名は動的に生成される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| Pester出力 | テスト実行時 | テスト名、結果、所要時間 |
| Warning | モジュールインポート時 | ソースからのインポート警告 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| テスト失敗 | 1件以上 | GitHub PR/コミットステータス |

## 備考

- 本スクリプトは.github/scripts/配下に配置されている
- PowerShell CoreとDesktopの両方に対応
- Coreの場合：localhost (sa/dbatools.I0認証)
- Desktopの場合：(localdb)\MSSQLLocalDB
- Azure接続文字列テストはCoreでのみ完全実行（Desktop時はスキップ）
- ファイル出力先はC:\temp（DAC Packageテスト）

### テスト一覧

| テスト名 | 対象機能 | 備考 |
|---------|---------|------|
| publishes a package | Export/Publish-DbaDacPackage | DAC Package操作 |
| connects to Azure using tenant and client id + client secret | Connect-DbaInstance | Service Principal認証 |
| connects to Azure using a query string | Connect-DbaInstance | 接続文字列認証 |
| gets a database from Azure | Get-DbaDatabase | Azureデータベース取得 |

### 環境別接続設定

| PowerShell Edition | SqlInstance | 認証方式 |
|-------------------|-------------|---------|
| Core | localhost | sa/dbatools.I0 |
| Desktop | (localdb)\MSSQLLocalDB | Windows統合認証 |
