コードへの不具合の混入を検出するため，ROSディストリビューションでは全てのパッケージに非常にたくさんのテストを繰り返しています．テストはちいさなユニットテストから，シミュレーションベースの大きな統合テストもあります．私たちのJenkins serverはそれらのテストを管理，運営しています．以下ではテストのそれぞれについてより詳細に述べます．

Contents

  1. 開発テスト(Development Tests)
    1. 何がテストされるのか？
    2. いつテストされるのか？
    3. だれが通知を受けるのか？
    4. 実行にどれくらい時間がかかる？
  2. Pull Request テスト(Pull Request Tests)
  3. リリース前テスト
    1. なにがテストされるのか？
    2. どのレポジトリがテストされるのか？
    3. いつテストが実行されるの？
    4. テストにどのくらい時間がかかる？
    5. リリース前テストの方法
      1. リリース前テストのための準備
      2. prerelease.pyコマンドの生成
      3. Running the Prerelease
    6. Examples
      1. A set of commands the website provides
      2. Customizing prerelease test commands
    7. What can I do when a prerelease fails?

search

開発テスト(Development Tests)

何がテストされるのか？

開発テストは各レポジトリの開発ブランチの全てのパッケージをビルドし，テストします．開発ブランチはdistribution.yaml rosdistroファイル (One from ROS Indigo | ROS Kinetic)の"source"セクションで指定されています．開発ブランチの名前はレポジトリのメンテナが決めますが，通常trunk/default/masterか，<DISTRO>-develとします．依存するパッケージはすべて前もってshadow-fixed repoからDebianパッケージがインストールされます．ビルドファームのリソースの制限により，現在のところ開発テストはUbuntu LTS(Long Term Support), amd64アーキテクチャに限られています．

いつテストされるのか？

開発ブランチにコミットするたびに，対応する開発テストが１時間以内に起動されます．ビルドファームの負荷が高い時には，ジョブが実行されるまで少し時間がかかるかもしれません．例えば，Indigoの開発テストのジョブはJenkinsで見ることができます．

だれが通知を受けるのか？

コミットした人が，ビルドが「成功した」もしくは「失敗した」と言った電子メールを受け取ります．開発テストのジョブが"unstable"となった場合(これは，警告やテストの失敗によるものです）には，最後の"stable"なビルドからコミットした全ての人々が通知を受け取ります．

実行にどれくらい時間がかかる？

一つのテストは通常１０分以下で終わります．ビルドファームがDebianパッケージのビルドで忙しい時には，ジョブの開始までもっと時間がかかることもあります．

Pull Request テスト(Pull Request Tests)

Pull requestテストは開発テストとほぼ同じで，ただ，ブランチに対するpull request により起動されるというものです．現在のところ， GitHub だけがサポートしています．

一般的にPull requestは必ず有効にしておく必要があります． (REP 143参照)．Indigoのpull requestテストのジョブはJenkinsで見ることができます．

リリース前テスト

パッケージの新しいリリースをpushする前に，レポジトリ内容についてリリース前テストを行うべきです．これによりROSコミュニティ全体のためのROS Debianパッケージのビルドを壊してしまったり，５分後にバグ修正のためのpushすることを避けることができます．ROS Jadeから，リリース前テストはdockerを使って自分のローカルマシンで行うことができます．自分のマシンでリリース前テストを行うためのコマンドラインツールの設定には，このウェブページ(http://prerelease.ros.org/ )を使います．

なにがテストされるのか？

(訳注：以下，http://prerelease.ros.org/ の画面についての説明です)

ビルドしてテストする（一つもしくは複数の）パッケージを選択します．必要となる依存パッケージはshadow-fixed repoのDebianパッケージから前もって全てインストールされます．加えて，あなたのパッケージに依存するパッケージもダウンロードし，ビルドし，テストすることができます．prerelease websiteに必要な分のパッケージをどのように設定するかの説明があります． 依存レベル(level of recursive dependent)の設定で，どのくらいの数のパッケージがテストされるかを調整できます．それに加えて，どんなパッケージもテストのために追加出来ます．もし特定のパッケージをビルドしたくない場合，例えば何らかの理由で壊れていることが分かっている場合，個別にパッケージのビルドを除外することができます．他のパッケージがテストされないこともありえますが．prerelease websiteには，テストされるパッケージが設定によってどのように変化するかが説明されています．（訳注：あまり説明はない気がする）

どのレポジトリがテストされるのか？

  • catkinパッケージについては，以下のバージョンのうちどれかを選べます．

    • version number: distribution.yaml rosdistro fileに一覧のあるreleaseレポジトリから，特定のバージョンのレポジトリ/スタックを取り出して用います．

    • latest: distribution.yaml rosdistro fileに一覧のあるreleaseレポジトリから，リリースされた最新バージョンのレポジトリ/スタックを取り出して用います.

distribution.yamlにリリースされた最新バージョンが含まれてない場合，GBPレポジトリが使われます（訳注：よく分かりません）

  • devel: 同じファイルの"source"レポジトリから開発用ブランチを取り出して使われます．もしrosdistroファイルがレポジトリのバージョンを含んでいない場合には，デフォルトのブランチが使われます．（訳注：よく分かりません）このファイルは手動で生成され，bloomによる自動リリースのプロセスではないことに注意してください - (手動の)pull requestによりリリースする必要があります．

  • 依存する全てのレポジトリ/スタックは常にrosdistroファイルの一覧にあるリリースバージョンがダウンロードされて持ちられます

  • distribution.yaml rosdistro fileの"repository"エントリの例を以下に示します: 

    •    1   rviz:  # <-- this is the repository's name
   2     doc:  # <-- this describes what to checkout for doc generation
   3       type: git
   4       url: https://github.com/ros-visualization/rviz.git
   5       version: hydro-devel
   6     release:  # <-- this is the "release" entry
   7       tags:
   8         release: release/hydro/{package}/{version}
   9       url: https://github.com/ros-gbp/rviz-release.git
  10       # ^-- url to the release repository
  11       version: 1.10.18-0  # <-- maps to "latest"
  12     source:  # <-- this is the "source" entry
  13     # ^-- maps to the "devel" prerelease option
  14       type: git
  15       url: https://github.com/ros-visualization/rviz.git
  16       version: hydro-devel
  17     status: maintained

いつテストが実行されるの？

リリース前テストは，行いたい時にローカルマシンで自分で実行します．

テストにどのくらい時間がかかる？

低位のレポジトリは一時間以上かかる場合もありますし，高位のレポジトリは５分程度で終わる場合もあります．テストにかかる時間は主に，テストされるパッケージにどのくらいのパッケージが依存しているかによります．あまりに長いテスト時間がかかる事のないように，prerelease websiteを使ってテストされるパッケージの数を調整することができます．

リリース前テストの方法

リリース前テストのための準備

まず，dockerをインストールする必要があります．docker.ioにあるこのインストールガイド にしたがってインストールしましょう．Ubuntu14.04のデフォルトのバージョンのdockerよりも新しい物が必要になるからです．dockerをsudoで実行しなくても良いように，自分のユーザをdockerグループに入れるのを忘れないようにしましょう．

ros-buildfarmパッケージにはリリース前テストに必要なスクリプトとツールが含まれており，これをインストールします． 

$ sudo apt-get install python3-ros-buildfarm

If you haven't installed ROS on your machine before, you'll also need to setup apt-get sources to include packages.ros.org. Run the following commands. 

$ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
$ sudo apt-key adv --keyserver hkp://pool.sks-keyservers.net --recv-key 421C365BD9FF1F717815A3895523BAEEB01FA116
$ sudo apt-get update

You can also install the Python 2 equivalent of the buildfarm, which is called python-ros-buildfarm. For the Python 2 package the template evaluation of the prerelease scripts still use Python 3 internally. Therefore you'll need to have EmPy for Python 3 installed. The Debian package is named python3-empy and is available from Ubuntu Trusty onward. For older versions of Ubuntu, or on other platforms, it can be installed with the following commands: 

  • $ sudo apt-get install python3 python3-pip
$ sudo python3 -m pip install -U EmPy

prerelease.pyコマンドの生成

コンピュータのセットアップができたら，ウェブサイト(http://prerelease.ros.org/)でリリース前テストに必要なコマンドを生成します．

このサイトでは，まず，ROSディストリビューションの選択画面となります．パッケージをリリースするディストリビューションを選びます．つぎに，以下の３ステップで，ターミナルに入力するためのコマンドが生成されます．

1. Select Repositories. このステップでは，リリース前テストをするためのパッケージを追加します．基本的にはこれからROSのサブセットをビルドするのですが，全てのパッケージのテストを行いたくはないですよね！そこでこのステップでは，あなたの新しい（複数の）パッケージをリストに加えます．もしそのパッケージがすでにビルドファームにある場合，ドロップダウンリストの中にそれがあるはずです．もしそのパッケージが全く新しいか，ドロップダウンリストに現れない場合，"Add a custom repository"ボタンを押して必要な情報を入力します．完了したら，Nextボタンを押します．

  1. Additional Options. In this step, you can choose a custom build farm config file (for advanced users). You should be able to use the default one without issues. You can also choose an operating system to target. This can be useful to test your release on a different OS than the one you're using for local development. Once you've chosen an OS, click Next.

  2. Select Dependents to Test. This step may take a bit of time to load. If your package is brand new, you can ignore the rest of this step and go to Step 4. If your package is already on the build farm and has dependencies, this step will automatically add those dependencies to your prerelease for testing, to ensure that your package's changes didn't break those packages. You can add or remove dependencies for testing as desired (but you should probably test all of them).

  3. The wizard is complete. Click the Generate Command button and copy the commands into your terminal and run them.

Running the Prerelease

Wait, you still haven't done the prerelease yet! Look at the terminal output carefully. The custom command you ran just created prerelease.py. To actually run the prerelease, run that file: 

$ ./prerelease.py

Be patient, the command takes a while. The prerelease takes place in a Docker container, and should automatically build your packages, test them, and print the results using catkin_test_results. Make sure that there are no failed tests, and your prerelease is done!

After prerelease, you can run catkin_test_results to get the result of the prerelease tests again. This is an optional step. In order to run that command you need catkin installed and sourced. You'll have to have ROS and catkin installed. Install catkin with the command 

  • $ sudo apt-get install ros-kinetic-catkin

At some point, you also need to source the setup.bash file before you try to use catkin_test_results, by using the command 

  • $ source /opt/ros/kinetic/setup.bash

You can do this at any point, rest assured that your system and environment will not affect the prerelease since they are executed inside the docker container.

Examples

Below a few common prerelease examples are described. The ros_buildfarm documentation contains additional information and examples on prereleases: https://github.com/ros-infrastructure/ros_buildfarm/blob/master/doc/jobs/prerelease_jobs.rst

A set of commands the website provides

The command set provided by the prerelease test website above would look like the following. Variables that you can configure on the website are surrounded with %%. 

mkdir -p /tmp/prerelease_job
cd /tmp/prerelease_job
generate_prerelease_script.py \
  https://raw.githubusercontent.com/ros-infrastructure/ros_buildfarm_config/production/index.yaml \
  %ROS_DISTRO% default ubuntu %UBUNTU_DISTRO% amd64 \
  %PACKAGE_TARGETED% \
  --level %DOWNSTREAM_DEPTH% \
  --output-dir ./
  • A concrete example: 
    mkdir -p /tmp/prerelease_job
cd /tmp/prerelease_job
generate_prerelease_script.py \
  https://raw.githubusercontent.com/ros-infrastructure/ros_buildfarm_config/production/index.yaml \
  kinetic default ubuntu xenial amd64 \
  moveit \
  --level 0 \
  --output-dir ./
    In this example, we're testing:
  • %ROS_DISTRO%: ROS Kinetic

  • %UBUNTU_DISTRO%: Ubuntu xenial

  • %PACKAGE_TARGETED%: moveit

  • %DOWNSTREAM_DEPTH%: 0 (i.e. we're not testing if the tests in the downstream packages pass. Depending on the number of packages, the downstream testing can take long)

Customizing prerelease test commands

As you see, the configuration of prerelease test is done by a script generate_prerelease_script.py (that was installed on your computer with python3-ros-buildfarm package). See its option with the help to get some idea for customization. 

generate_prerelease_script.py --help
usage: generate_prerelease_script.py [-h] --output-dir OUTPUT_DIR
                                     [--custom-branch [REPO_NAME:BRANCH_OR_TAG_NAME [REPO_NAME:BRANCH_OR_TAG_NAME ...]]]
                                     [--custom-repo [REPO_NAME:REPO_TYPE:REPO_URL:BRANCH_OR_TAG_NAME [REPO_NAME:REPO_TYPE:REPO_URL:BRANCH_OR_TAG_NAME ...]]]
                                     [--pkg [PACKAGE_NAME [PACKAGE_NAME ...]]]
                                     [--exclude-pkg [PACKAGE_NAME [PACKAGE_NAME ...]]]
                                     [--level DEPENDENCY_LEVEL]
                                     config_url rosdistro_name
                                     source_build_name os_name os_code_name
                                     arch [REPO_NAME [REPO_NAME ...]]

Generate a 'prerelease' script

positional arguments:
  config_url            The url of the ROS buildfarm configuration index
  rosdistro_name        The name of the ROS distro from the index
  source_build_name     The name / key of the 'source-build' file from the
                        index
  os_name               An OS name from the build file
  os_code_name          An OS code name from the build file
  arch                  An architecture from the build file

optional arguments:
  -h, --help            show this help message and exit
  --output-dir OUTPUT_DIR
                        The output directory

Repositories in underlay workspace:
  The repositories in the underlay workspace will be built and installed as
  well as built and tested. Dependencies will be provided by binary
  packages.

  REPO_NAME             A name of a 'repository' from the distribution file
  --custom-branch [REPO_NAME:BRANCH_OR_TAG_NAME [REPO_NAME:BRANCH_OR_TAG_NAME ...]]
                        A name of a 'repository' from the distribution file
                        followed by a colon and a branch / tag name
  --custom-repo [REPO_NAME:REPO_TYPE:REPO_URL:BRANCH_OR_TAG_NAME [REPO_NAME:REPO_TYPE:REPO_URL:BRANCH_OR_TAG_NAME ...]]
                        The name, type, url and branch / tag name of a repository,
                            'e.g. "common_tutorials:git:https://github.com/ros/common_tutorials:pullrequest-1"')

Packages in overlay workspace:
  The packages in the overlay workspace will be built and tested. The
  workspace will be extended with packages from GBP repositories for
  dependencies between the overlay and underlay workspaces. All other
  dependencies will be provided by binary packages.

  --pkg [PACKAGE_NAME [PACKAGE_NAME ...]]
                        A name of a released 'package' from the distribution
                        file to be included in the overlay workspace
  --exclude-pkg [PACKAGE_NAME [PACKAGE_NAME ...]]
                        A name of a released 'package' from the distribution
                        file which should be excluded from the overlay
                        workspace
  --level DEPENDENCY_LEVEL
                        The depth of the depends-on tree to be included in the
                        overlay workspace (-1 implies unlimited, default: 2)

For example,

  • to run prerelease test using a pull request that's not yet merged, you can do something like this: 
    generate_prerelease_script.py   https://raw.githubusercontent.com/ros-infrastructure/ros_buildfarm_config/production/index.yaml indigo default ubuntu trusty amd64  moveit   --level 0 --custom-repo moveit:git:https://github.com/130s/moveit:fix/5   --output-dir ./

What can I do when a prerelease fails?

Once the generate prerelease command is finished, it will instruct you to run the ./prerelease.sh shell script. This in turn runs a shell script for each step of the prerelease. If a step fails, then you can edit the files which are local (not stored inside the docker container) and then each step of the prerelease process can be rerun by executing the corresponding shell script. These are the steps that you might want to rerun:

  • prerelease_clone_underlay.sh: checkouts source code for the repositories you specified

  • prerelease_clone_overlay.sh: checkouts source code for the dependent packages you are going to test on top of the repositories you specified

  • prerelease_build_underlay.sh: builds and tests the packages in the repositories you specified

  • prerelease_build_overlay.sh: builds and tests the dependent packages on top of the repositories built and tested in the "build_underlay" step

If you look in the folder where you ran the prerelease then you'll also notice some folders of interest when debugging:

  • catkin_workspace: "underlay" catkin workspace in which the repositories you selected are built and tested

  • catkin_workspace_overlay: catkin workspace in which dependent packages are built; it is chained on top of the "underlay" catkin workspace

You can modify code in these two repositories and rerun one or more of the above shell scripts to iterate on the prerelease test and try to resolve issues.

Wiki: ja/regression_tests (last edited 2018-01-31 04:20:16 by RyosukeTajima)

Except where otherwise noted, the ROS wiki is licensed under the
Creative Commons Attribution 3.0