diff --git a/.github/workflows/integration-windows.yml b/.github/workflows/integration-windows.yml new file mode 100644 index 0000000..eff94d3 --- /dev/null +++ b/.github/workflows/integration-windows.yml @@ -0,0 +1,154 @@ +name: Integration (Windows) + +# com0com の仮想 COM ポート対と serdevmock を使い、FFI 実装の送受信を実機なしで確かめる。 +# FFI 実装に関係しない変更まで走らせないよう、macOS 版と同じく実行の機会を絞る。 +on: + workflow_dispatch: + schedule: + # 毎週月曜 03:00(日本時間) + - cron: '0 18 * * 0' + pull_request: + branches: [ main ] + paths: + - '.github/workflows/integration-windows.yml' + - 'tests/Integration/**' + - 'tests/fixtures/serdevmock/**' + - 'tests/fixtures/windows/**' + - 'src/PhpSerial/Platform/Windows*.php' + +permissions: + contents: read + +jobs: + serdevmock: + name: serdevmock - windows-latest + runs-on: windows-latest + # 相手が読まないと write() が戻らない経路があるため、上限を設けて CI を止めない + timeout-minutes: 15 + defaults: + run: + shell: pwsh + env: + # SourceForge の com0com 3.0.0.0 署名版。ハッシュが合わなければ導入しない + COM0COM_ZIP_URL: https://sourceforge.net/projects/com0com/files/com0com/3.0.0.0/com0com-3.0.0.0-i386-and-x64-signed.zip/download + COM0COM_ZIP_SHA256: 6e5d4359865277430d4ae88c73fb7e648a0ed8e81aea5002478179cfcb0bb0e1 + COM0COM_SETUP: Setup_com0com_v3.0.0.0_W7_x64_signed.exe + APP_PORT: COM10 + MOCK_PORT: COM11 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Setup PHP + uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0 + with: + php-version: '8.5' + extensions: ffi + ini-values: ffi.enable=true + coverage: none + + # FFI が無効だと SerialPort は fopen 版へ切り替わり、FFI 実装を試験しないまま通ってしまう + - name: Check FFI + run: | + $info = php --ri ffi + if ($LASTEXITCODE -ne 0) { + throw 'FFI 拡張が読み込まれていない' + } + $info + if (-not ($info -match '^ffi\.enable => (true|on|1)\b')) { + throw 'ffi.enable が有効になっていない' + } + + - name: Install dependencies + run: composer install --prefer-dist --no-progress + + - name: Setup Python + uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: '3.13' + + - name: Install serdevmock + run: python -m pip install --require-hashes -r tests/Integration/requirements.txt + + # ホストランナーは Secure Boot が無効のため、2016 年の証明書で署名されたドライバーも読み込める + - name: Install com0com + id: com0com + timeout-minutes: 3 + run: | + $work = Join-Path $env:RUNNER_TEMP 'com0com' + $installDir = Join-Path $work 'install' + $zip = Join-Path $work 'com0com.zip' + New-Item -ItemType Directory -Force $work | Out-Null + + curl.exe -fsSL --retry 3 -o $zip $env:COM0COM_ZIP_URL + $hash = (Get-FileHash -Algorithm SHA256 $zip).Hash.ToLowerInvariant() + if ($hash -ne $env:COM0COM_ZIP_SHA256) { + throw "com0com の SHA256 が一致しない: $hash" + } + + Expand-Archive -Path $zip -DestinationPath (Join-Path $work 'zip') + $setup = Join-Path $work "zip\$env:COM0COM_SETUP" + + # 発行元を信頼済みにしておかないと、ドライバー導入の確認ダイアログで止まる。 + # 使い捨てのランナーに限った操作であり、手元では行わない + $cert = (Get-AuthenticodeSignature $setup).SignerCertificate + $store = [System.Security.Cryptography.X509Certificates.X509Store]::new('TrustedPublisher', 'LocalMachine') + $store.Open('ReadWrite') + try { + $store.Add($cert) + } finally { + $store.Close() + } + + $p = Start-Process -FilePath $setup -ArgumentList '/S', "/D=$installDir" -Wait -PassThru + if ($p.ExitCode -ne 0) { + throw "com0com のインストーラーが失敗した: $($p.ExitCode)" + } + + Push-Location $installDir + try { + .\setupc.exe --silent install "PortName=$env:APP_PORT" "PortName=$env:MOCK_PORT" + if ($LASTEXITCODE -ne 0) { + throw "setupc が失敗した: $LASTEXITCODE" + } + .\setupc.exe list + } finally { + Pop-Location + } + + $ports = [System.IO.Ports.SerialPort]::GetPortNames() + foreach ($name in $env:APP_PORT, $env:MOCK_PORT) { + if ($ports -notcontains $name) { + throw "$name が見つからない: $($ports -join ', ')" + } + } + + # Windows のランナーは、ステップ内で起動したプロセスをステップの終わりに止める。 + # このため serdevmock の起動・試験・停止を 1 つのステップで行う。 + # 環境変数が欠けて全件が飛ばされたまま緑になるのを防ぐため、skip と空を失敗として扱う + - name: Run integration tests with serdevmock + timeout-minutes: 3 + env: + SERDEVMOCK_PORT: ${{ env.APP_PORT }} + run: | + $work = Join-Path $env:RUNNER_TEMP 'serdevmock' + try { + ./tests/Integration/start-serdevmock.ps1 -AppPort $env:APP_PORT -MockPort $env:MOCK_PORT -WorkDir $work + php vendor/bin/phpunit --group integration --testdox --fail-on-skipped --fail-on-empty-test-suite + $code = $LASTEXITCODE + } finally { + ./tests/Integration/stop-serdevmock.ps1 -WorkDir $work + } + exit $code + + # serdevmock を止めた後の COM10 は、相手が読まないポートになる + - name: Run idle port tests + if: ${{ !cancelled() && steps.com0com.outcome == 'success' }} + timeout-minutes: 3 + env: + WINDOWS_IDLE_PORT: ${{ env.APP_PORT }} + run: >- + php vendor/bin/phpunit --group windows-idle-port --testdox + --fail-on-skipped --fail-on-empty-test-suite diff --git a/README.md b/README.md index 006d50d..db02579 100644 --- a/README.md +++ b/README.md @@ -183,6 +183,7 @@ composer test 実機なしで送受信を確かめる結合テストもあります。 serdevmock と仮想ポートの対を使います。 +CI では、Linux を push と PR のたびに、macOS と Windows を週 1 回と関係する PR で実行します。 手順は [docs/INTEGRATION_TESTING.md](docs/INTEGRATION_TESTING.md) を参照してください。 ## 使用例 diff --git a/docs/INTEGRATION_TESTING.md b/docs/INTEGRATION_TESTING.md index 74a6c81..862538d 100644 --- a/docs/INTEGRATION_TESTING.md +++ b/docs/INTEGRATION_TESTING.md @@ -6,7 +6,8 @@ 実機を使わずに、ポートを開いて送受信するまでを確かめる手順をまとめます。 仮想ポートの対を作り、片側で serdevmock を動かします。 もう片側を php-serial で開き、送ったデータがそのまま返るかを確かめます。 -Linux は CI で毎回、macOS は CI で週 1 回、Windows は手元で確かめます。 +Linux は CI で毎回、macOS と Windows は CI で週 1 回確かめます。 +Windows は手元でも確かめられます。 ## 📑 目次 @@ -41,7 +42,7 @@ serdevmock には `tests/fixtures/serdevmock/echo.json` を読ませます。 |---|---|---| | Linux | socat | CI(push と PR ごと) | | macOS | socat | CI(手動、週 1 回、関係する PR) | -| Windows | com0com | 手元 | +| Windows | com0com | CI(手動、週 1 回、関係する PR)と手元 | ## 🐧 Linux と macOS @@ -100,6 +101,17 @@ vendor\bin\phpunit --group integration --testdox `.env` に `SERDEVMOCK_PORT=COM10` と書いても指定できます。 +serdevmock を別のターミナルで動かす代わりに、起動スクリプトも使えます。 +CI と同じく、エコーが返るのを確かめてから戻ります。 + +```powershell +pwsh tests\Integration\start-serdevmock.ps1 -AppPort COM10 -MockPort COM11 -WorkDir $env:TEMP\serdevmock -Serdevmock .\.venv-serdevmock\Scripts\serdevmock.exe +``` + +```powershell +pwsh tests\Integration\stop-serdevmock.ps1 -WorkDir $env:TEMP\serdevmock +``` + ### 相手が読まないポートでの試験 serdevmock を止めると、COM10 は「相手が読まないポート」になります。 @@ -116,23 +128,61 @@ serdevmock の試験と同時には指定しないでください。 ## ⚙ CI での扱い -Linux は `.github/workflows/integration.yml` で、push と PR のたびに実行します。 -macOS は `.github/workflows/integration-macos.yml` で実行します。 +表 2. OS ごとのワークフローと実行の機会 + +| OS | ワークフロー | 実行の機会 | +|---|---|---| +| Linux | `integration.yml` | push と PR のたび | +| macOS | `integration-macos.yml` | 手動、週 1 回、関係する PR | +| Windows | `integration-windows.yml` | 手動、週 1 回、関係する PR | + +ワークフローは `.github/workflows/` にあります。 macOS ランナーは空き待ちが 10 分前後になることがあるため、実行の機会を絞っています。 +Windows のジョブは 1 分ほどで終わります。 +ただし FFI 実装に関係しない変更まで走らせないよう、macOS に合わせています。 +どちらも次の機会に実行します。 - 手動実行(`workflow_dispatch`) - 毎週月曜 03:00(日本時間) -- 結合テストの仕組みか `Unix.php` を変えた PR +- 結合テストの仕組みか、その OS のプラットフォーム実装を変えた PR + +関係する PR の判定には、macOS は `Unix.php`、Windows は `Windows.php` と `WindowsFFI.php` を使います。 -どちらも `--fail-on-skipped` と `--fail-on-empty-test-suite` を付けて実行します。 +いずれも `--fail-on-skipped` と `--fail-on-empty-test-suite` を付けて実行します。 環境変数の設定漏れで全件が skip されたまま、緑になるのを防ぐためです。 +### 🪟 Windows ランナーでの com0com + +Windows のジョブは、com0com 3.0.0.0 の署名版を SourceForge から取得します。 +SHA256 を照合してから、インストーラーを `/S` で非対話のまま実行します。 +続けて `setupc.exe` で COM10 と COM11 の対を作ります。 + +インストーラーの前に、署名者の証明書を「信頼された発行元」へ登録します。 +登録しないと、ドライバー導入の確認ダイアログで止まるためです。 +この操作は使い捨てのランナーに限り、手元では行いません。 + +このドライバーは 2016 年の証明書で署名されています。 +Secure Boot が有効な Windows 10 以降では、読み込みを拒まれることがあります。 +GitHub のホストランナーは Secure Boot が無効のため、そのまま読み込めます。 +ランナーの構成が変わって導入に失敗したときは、この点を最初に疑ってください。 + +ジョブは 2 段で試験します。 +まず serdevmock を COM11 で動かし、COM10 で `integration` グループを流します。 +次に serdevmock を止め、COM10 で `windows-idle-port` グループを流します。 + +Windows のランナーは、ステップ内で起動したプロセスをステップの終わりに止めます。 +このため、serdevmock の起動・試験・停止を 1 つのステップにまとめています。 +分けると、試験の時点で serdevmock が止まっており、エコーが返りません。 + +FFI が無効だと、php-serial は fopen 版の実装へ切り替わります。 +FFI 実装を試験しないまま通るのを防ぐため、最初に `php --ri ffi` で有効化を確かめます。 + ## 🔍 この試験で見つけた問題 Windows の FFI 実装で、次の問題を見つけて直しました。 同じ問題が戻ってきたときは、ここに挙げたテストが失敗します。 -表 2. 見つけた問題と、それを確かめるテスト +表 3. 見つけた問題と、それを確かめるテスト | 問題 | 確かめるテスト | |---|---| diff --git a/tests/Integration/start-serdevmock.ps1 b/tests/Integration/start-serdevmock.ps1 new file mode 100644 index 0000000..b2341f9 --- /dev/null +++ b/tests/Integration/start-serdevmock.ps1 @@ -0,0 +1,99 @@ +<# +com0com の対の片側で、エコーモードの serdevmock を動かす(Windows 用)。 + +使い方: pwsh tests/Integration/start-serdevmock.ps1 -AppPort COM10 -MockPort COM11 -WorkDir <作業ディレクトリ> + +-AppPort は php-serial 側、-MockPort は serdevmock 側のポートである。 +serdevmock が PATH に無いときは、-Serdevmock に実行ファイルのパスを渡す。 +停止は stop-serdevmock.ps1 に同じ -WorkDir を渡して行う。 +#> +[CmdletBinding()] +param( + [Parameter(Mandatory)][string]$AppPort, + [Parameter(Mandatory)][string]$MockPort, + [Parameter(Mandatory)][string]$WorkDir, + [string]$Serdevmock = 'serdevmock' +) + +$ErrorActionPreference = 'Stop' + +$fixtureDir = Join-Path $PSScriptRoot '..\fixtures\serdevmock' +$exe = (Get-Command $Serdevmock -CommandType Application | Select-Object -First 1).Source + +New-Item -ItemType Directory -Force $WorkDir | Out-Null +$WorkDir = (Resolve-Path $WorkDir).Path + +$env:PYTHONUNBUFFERED = '1' +# 出力先がファイルだと既定の文字コードになり、serdevmock の日本語のメッセージで落ちる +$env:PYTHONIOENCODING = 'utf-8' +# 設定ファイルは作業ディレクトリからの相対名で渡し、パスの空白で引数が割れるのを避ける +$proc = Start-Process -FilePath $exe -PassThru -WindowStyle Hidden ` + -WorkingDirectory $fixtureDir ` + -ArgumentList '--protocol', 'uart', '--port', $MockPort, '--config', 'echo.json' ` + -RedirectStandardOutput (Join-Path $WorkDir 'serdevmock.log') ` + -RedirectStandardError (Join-Path $WorkDir 'serdevmock.err.log') +Set-Content -Path (Join-Path $WorkDir 'serdevmock.pid') -Value $proc.Id + +function Write-SerdevmockLog { + foreach ($name in 'serdevmock.log', 'serdevmock.err.log') { + $path = Join-Path $WorkDir $name + if (Test-Path $path) { + Write-Host "----- $name" + Get-Content $path | Write-Host + } + } +} + +# serdevmock はポートを開くときに受信バッファを捨てる。 +# 開き終える前に送ったデータは失われるため、エコーが返るまで確かめてから戻る。 +$port = [System.IO.Ports.SerialPort]::new($AppPort, 9600) +$port.NewLine = "`n" +$port.ReadTimeout = 1000 +# 相手が読まないと書き込みが戻らないため、上限を設ける +$port.WriteTimeout = 1000 +$ready = $false + +$port.Open() +try { + for ($i = 1; $i -le 30 -and -not $ready; $i++) { + # 起動直後に落ちた場合は、待ち続けずに打ち切る + if ($proc.HasExited) { + break + } + + $probe = "probe-$i" + try { + $port.WriteLine($probe) + } catch [System.TimeoutException] { + continue + } + $deadline = [DateTime]::UtcNow.AddSeconds(1) + + while (-not $ready -and [DateTime]::UtcNow -lt $deadline) { + try { + $ready = $port.ReadLine().TrimEnd("`r") -eq $probe + } catch [System.TimeoutException] { + break + } + } + } + + # 遅れて届いた古い応答を読み捨て、テストへ持ち越さない + try { + while ($true) { + [void]$port.ReadLine() + } + } catch [System.TimeoutException] { + } +} finally { + $port.Close() +} + +if (-not $ready) { + Write-SerdevmockLog + # 呼び出し元が後続の試験へ進まないよう、終了コードでなく例外で知らせる + throw 'serdevmock からエコーが返らなかった' +} + +Write-Host "php-serial 側: $AppPort / serdevmock 側: $MockPort" +Write-Host 'serdevmock の準備ができた' diff --git a/tests/Integration/stop-serdevmock.ps1 b/tests/Integration/stop-serdevmock.ps1 new file mode 100644 index 0000000..7eeaf01 --- /dev/null +++ b/tests/Integration/stop-serdevmock.ps1 @@ -0,0 +1,36 @@ +<# +start-serdevmock.ps1 で起動した serdevmock を止め、ログを出す(Windows 用)。 + +使い方: pwsh tests/Integration/stop-serdevmock.ps1 -WorkDir <作業ディレクトリ> +#> +[CmdletBinding()] +param( + [Parameter(Mandatory)][string]$WorkDir +) + +$pidFile = Join-Path $WorkDir 'serdevmock.pid' + +if (Test-Path $pidFile) { + $id = [int](Get-Content $pidFile -TotalCount 1) + $proc = Get-Process -Id $id -ErrorAction SilentlyContinue + + if ($null -eq $proc) { + # 試験の途中で落ちていた場合は、失敗の原因として目に付くように残す + Write-Warning 'serdevmock は停止の前に終了していた' + } else { + # serdevmock.exe は python.exe を子として起動するため、子まで含めて止める + & taskkill.exe /PID $id /T /F | Out-Null + # ポートが閉じ切る前に次の試験が開くと、使用中で失敗するため終了を待つ + $null = $proc.WaitForExit(5000) + } + + Remove-Item $pidFile -Force +} + +foreach ($name in 'serdevmock.log', 'serdevmock.err.log') { + $path = Join-Path $WorkDir $name + if (Test-Path $path) { + Write-Host "----- $name" + Get-Content $path | Write-Host + } +}