Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 154 additions & 0 deletions .github/workflows/integration-windows.yml
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,7 @@ composer test

実機なしで送受信を確かめる結合テストもあります。
serdevmock と仮想ポートの対を使います。
CI では、Linux を push と PR のたびに、macOS と Windows を週 1 回と関係する PR で実行します。
手順は [docs/INTEGRATION_TESTING.md](docs/INTEGRATION_TESTING.md) を参照してください。

## 使用例
Expand Down
64 changes: 57 additions & 7 deletions docs/INTEGRATION_TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
実機を使わずに、ポートを開いて送受信するまでを確かめる手順をまとめます。
仮想ポートの対を作り、片側で serdevmock を動かします。
もう片側を php-serial で開き、送ったデータがそのまま返るかを確かめます。
Linux は CI で毎回、macOS は CI で週 1 回、Windows は手元で確かめます。
Linux は CI で毎回、macOS と Windows は CI で週 1 回確かめます。
Windows は手元でも確かめられます。

## 📑 目次

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 は「相手が読まないポート」になります。
Expand All @@ -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. 見つけた問題と、それを確かめるテスト

| 問題 | 確かめるテスト |
|---|---|
Expand Down
99 changes: 99 additions & 0 deletions tests/Integration/start-serdevmock.ps1
Original file line number Diff line number Diff line change
@@ -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 の準備ができた'
Loading
Loading