ロボットシステム学

第7回: GitHubでのテスト

千葉工業大学 上田 隆一

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

今日やること

• GitHub Actions
• READMEの整備

1. GitHub Actions

ソフトウェアのテスト

• 前回体験
  • 自分で使うソフトウェアならこれくらいで十分
• 仕事や人の使うソフトウェアの場合は？
  • 様々な環境に対応する必要性
    • Pythonのバージョン
    • Linuxだけじゃなく、他のOSは？
    • 自分の使っている環境（いろんなものが既にインストール済み）以外
  • 常に動作しているものが存在
    • 止めないでどうやって開発したものをマージするのか
  • ちゃんとテストしていると示したい

テストが（も）できるウェブサービス

• そういうものが存在
  • CircleCI
  • Travis CI
  • ・・・
• 基本的な動作
  1. GitHub等にpushされたコードをテスト
  • GitHub等のページに結果が表示されるように手配
  2. テストが通ったら次のアクションに
  • リリースしてユーザーが利用可能に
  • あるいは動いている本番のシステムに反映

改めてテストの役割

• 抜け目のないテストにより
  • デバッグやリリースの際の手間の削減が可能
  • 「動いているシステムは怖くていじれない」からの脱却
    • 「継続的インテグレーション（CI）」「継続的デリバリー（CD）」「継続的デプロイ」
    • CircleCIやTravis CIのサービス（CI/CDサービス）のテスト機能: CIやCDを実現するためのもの
• 「自動」でテストできることがキモ
  • 自動化の仕組み: テストの終了ステータスが0自動化のプログラムを起動

GitHub Actions

• GitHubのCI/CDサービス
  • CircleCIやTravis CIより後発だが、GitHubにくっついていて使いやすいため、この講義で利用
  • テストをするときの使い方
    • リポジトリに.github/workflowsというディレクトリを作成
    • その中に.ymlというファイル（ワークフローファイル）を作成
      • とりあえずtest.ymlで
    • テストの手続きを記述（次ページ）

$ mkdir .github    #robosys2022のリポジトリのトップディレクトリで
$ cd .github/      #.githubディレクトリは隠れディレクトリになるので注意（lsで出てこない。ls -aで出る。）
$ mkdir workflows
$ cd workflows/
$ touch test.yml   #「./robosys2022/.github/workflows/test.yml」ができているとOK

テストの手続きの記述

• 下の例のように記述
  • YAML（YAML Ain't a Markup Language）形式
    • データをテキストファイルに記述するときに使われる形式のひとつ
      • ROSでも随所に利用される。
    • インデントは半角空白2つが基本
      • 「キー: 値」でデータを作る。インデントされているものは全体が値
      • 「-」は配列の要素

  name: test        #name: ワークフローの名前
  on: push          #on: いつこのワークフローを走らせるか
  jobs:             #走らせたい処理（ジョブ）のリスト
    test:           #testというジョブを作る
      runs-on: ubuntu-latest   #どの環境で動かすか
      steps:                   #手続きの記述
      - uses: actions/checkout@v3  #https://github.com/actions/checkoutのバージョン3を使用
      - name: All test             #このジョブの名前
        run: bash -xv ./test.bash  #テストのシェルスクリプトを走らせる

pushワークフローの自動実行

• リポジトリのページに小さな記号
  • : 実行中、: テスト成功、: テスト失敗
    
• 記号を左クリックすると小窓が出現「Details」を押してみましょう。
  

ワークフローのログ確認

• Detailsを押すと行われた処理のシェルの出力が閲覧可能
  • 「All test」をクリックするとtest.bashのログ
    
• 全項目の終了ステータスが0ならの表示

複数バージョンのPythonを試す

• ジョブにstrategy/matrix/python-versionを追加

  ・・・
  jobs:
    test:
      runs-on: ubuntu-latest
      strategy:
        matrix:
          python-version: ["3.7", "3.8", "3.9", "3.10"]
      steps:
        ・・・
  

  • 実行してみると、全バージョンに対してテストが走る
    

2. READMEの整備

• README: このソフトを使ってもらうときに最初に読んでもらうドキュメント
  • 練習リポジトリの中あるREADME.mdがソレ

  # robosys2022
  ロボットシステム学の練習リポジトリ
  

  • Markdownという形式で記述
  • GitHubだとこのように表示される
    • 今のところ不親切

READMEに書くこと

• 全て書く必要はないが、ユーザが困らないように（例）
  • 何をするためのソフトか
  • 使い方
    • ダウンロード、インストール、起動する手順、簡単な使い方
  • どんな環境で使えるか
    • OS/Pythonのバージョン/他に必要なソフトウェアやライブラリ
  • テストの結果（後述）
  • 権利関係・謝辞
    • 著作権、ライセンス（利用しているソフトウェアについても）
    • 手伝ってくれた人のリストと手伝いの中身
  • その他必要なこと

テスト結果やテストに対する記述

• README.mdの例

  # plusコマンド
  ![test](https://github.com/ryuichiueda/robosys2022/actions/workflows/test.yml/badge.svg)
  ↑ テスト結果を反映したバッジの画像が埋め込まれる。（ryuichiueda等は各自変更を。）
  
  標準入力から読み込んだ数字を足す。
  
  （ここに前ページの項目をいろいろ書く）
  
  ## 必要なソフトウェア
  - Python
    - テスト済みバージョン: 3.7〜3.10
  
  ## テスト環境
  - Ubuntu 24.04 LTS
  
  © 2022 Ryuichi Ueda
  

GitHub上での表示

まとめ

• CI/CDサービスのひとつを利用
  • pushしたときに自動でテスト結果を表示
    • ユーザに状況を伝達
  • 終了ステータスを利用
    • 最新のサービスでも基本的な仕組みに依存
• READMEの整備
  • リポジトリのソフトを安心して広く使ってもらうために必須
  • ある程度フォーマットは決まっているものの、ユーザへの気配り重視で記述しましょう。

課題1（詳細はmanabaで）

• robosys2024のリポジトリでなにかコマンドを作る
  • コマンドなので・・・
    • 標準入力からなにか字を読んで、標準出力から加工して出力
• robosys2024リポジトリの充実
  • READMEをちゃんと書く
  • GitHub Actionsでいろんなテストをする
  • 著作権、ライセンスの問題を解決する
• 今年はplusコマンドは禁止しますー