11.07.2014

Integrating Your Python Projects with Travis-CI and Coveralls

Python: GitHub 上のプロジェクトを Travis-CI, Coveralls と連携する

 

GitHub でパブリックなプロジェクトを作ったら、無料でCI環境とカバレッジ環境を手に入れることが可能。
これを利用しない手はない。

以下、具体例として一つの小さなプロジェクトを作りながら説明する。

 

Step 1: GitHub リポジトリ作成

setup.py で管理された Python プロジェクトを作る。

ディレクトリ構成

構成の一例。

.
├── .gitignore
├── .travis.yml
├── LICENSE
├── README.md
├── setup.py
├── src
│   └── yourpackage
│       ├── __init__.py
│       └── yourmodule.py
└── tests
    ├── __init__.py
    └── test_yourmodule.py

 

アプリケーション/ライブラリの実装

ソースコードは src ディレクトリ配下にまとめる。

ここでは例として yourpackage というパッケージと、適当な数値計算を行うyour_function という関数を用意した。

__init__.py にインポート対象(クラス/関数)を書くのを忘れずに。

from .yourmodule import your_function
def your_function(x):
    ret = 0
    if x % 2:
        ret |= 1
    if x < 10000:
        ret |= 2
    if x == 10000:
        ret |= 4
    if x % 9 == 7:
        ret |= 8
    if x / 2000 == 6:
        ret |= 16
    return ret
テストコードの実装

テストコードは tests ディレクトリ配下にまとめる。

tests 自体もパッケージとして管理したほうが利便性がよいので、空の __init__.py を作る。
そして以下のようなテストコードを書いた。

import unittest
from yourpackage import your_function


class TestYourModule(unittest.TestCase):
    def setUp(self):
        pass

    def test_your_function_zero(self):
        self.assertEqual(your_function(0), 2)

    def test_your_function_odd(self):
        self.assertEqual(your_function(1), 3)

    def test_your_function_greater_than_10000(self):
        self.assertEqual(your_function(10006), 8)

    def test_your_function_12345(self):
        self.assertEqual(your_function(12345), 17)

カバレッジ結果をわかりやすくするため、あえてカバレッジ率は 100% にならないようにしている。

setup.py セットアップスクリプトの記述

今回は必要ないが、他の Python ライブラリに依存があればここで記述する。

from setuptools import setup, find_packages

setup(
    name='your-project-name',
    version='0.0.1',
    description='description for your project',
    author='your name',
    author_email='your email address',
    url='your url',
    install_requires=[
        # list your dependencies
    ],
    tests_require=[
        # dependencies for unit testing
    ],
    package_dir={'': 'src'},
    packages=find_packages('src'),
    include_package_data=True,
    test_suite='tests',
)
テストの実行

setup.py を使ってテストを実行する。以下のように表示されれば OK。

$ python ./setup.py test
running test
running egg_info
creating src/your_project_name.egg-info
writing src/your_project_name.egg-info/PKG-INFO
writing top-level names to src/your_project_name.egg-info/top_level.txt
writing dependency_links to src/your_project_name.egg-info/dependency_links.txt
writing manifest file 'src/your_project_name.egg-info/SOURCES.txt'
reading manifest file 'src/your_project_name.egg-info/SOURCES.txt'
writing manifest file 'src/your_project_name.egg-info/SOURCES.txt'
running build_ext
test_your_function_12345 (tests.test_yourmodule.TestYourModule) ... ok
test_your_function_greater_than_10000 (tests.test_yourmodule.TestYourModule) ... ok
test_your_function_odd (tests.test_yourmodule.TestYourModule) ... ok
test_your_function_zero (tests.test_yourmodule.TestYourModule) ... ok

----------------------------------------------------------------------
Ran 4 tests in 0.000s

OK

ここまでできたら、一旦 GitHub に公開リポジトリとして push する。

 

Step 2: Travis-CI の登録

  • https://travis-ci.org/ にアクセス
  • メニュー右上の Sign in with GitHub をクリックし、GitHub OpenID認証を承認
  • ログイン後、アカウント名 -> Accounts -> Repositories の画面で
    連携したいプロジェクトをチェック・オン
    Travis CI Free Hosted Continuous Integration Platform for the Open Source Community

 

Step 3: Coveralls の登録

  • https://coveralls.io/ にアクセス
  • メニュー右上の SIGN IN ボタンをクリックし、GitHub OpenID認証を承認
  • ログイン後、REPOS -> ADD REPOS ボタンをクリック
  • リストに対象リポジトリが表示されていなかったら、画面上部の SYNC GITHUB REPOS ボタンをクリック
  • 連携したいプロジェクトをチェック・オン
    Coveralls Test Coverage History Statistics

 

Step 4: .travis.yml の設置

プロジェクトルートに、.travis.yml という名前の設定ファイルを作れば
Travis-CI がそのファイルを読み取ってテストを走らせてくれる。

こちら (Travis CI: Building a Python Project) を参考に、以下のような内容で記述。

---
language: python
python:
  - "2.6"
  - "2.7"
install:
  - pip install coveralls
script:
  - coverage run --source=src setup.py test
after_success:
  - coveralls

install, script, after_success に Coveralls 連携のための記述を追加していることに注意。

この状態で GitHub に push を行えば、ほどなく(数分以内に)自動的に Travis-CI, Coverall の処理が開始される。

 

Step5: 結果確認

Travis-CI, Coverall ともに GUI ですぐに結果を確認できる。
またテストに失敗した場合は、自動的に通知メールが飛んでくる。 

  • Travis-CI
    Travis CI Free Hosted Continuous Integration Platform for the Open Source Community
  • Coveralls
    Mogproject skeleton python Coveralls Test Coverage History Statistics

    ファイル単位のカバレッジももちろん閲覧可能。
    Mogproject skeleton python Job 1 src yourpackage yourmodule py Coveralls Test Coverage History Statistics

 

Step 6: バッジの登録

Travis-CI, Coveralls ともに公式のバッジが用意されている。

  • Travis-CI
    Travis CI Free Hosted Continuous Integration Platform for the Open Source Community
  • Coveralls
    Mogproject skeleton python Coveralls Test Coverage History Statistics 

これらを README に貼り付ければ、GitHub 訪問者にとってもステータスが一目瞭然だ。
Mogproject skeleton python 

さいごに

今回は Python プロジェクトの例を挙げたが、setup.py やテストコードの準備さえ済めば、実に簡単に連携できる。

まさに朝飯前。『Web系エンジニアにとってテストコードを書くのは朝起きて歯磨きをするように当たり前のこと』との言もあったが、これらのサービスはさながら無料の朝食サービスのようなものだ。

より高度な使い方もできるので、詳細は各サービスのドキュメントを参照。以下はその一例。

  • master 以外のブランチと連携
  • pull request との連携 (マージする前に結果を確認できるので便利)
  • 通知先の拡張 (チャットサービス等と連携)
  • プライベートリポジトリとの連携 (有償)

Travis-CI, Coveralls ともに他の言語でも利用可能なので、今後も積極的に活用していきたい。

 

今回使用したコード

 

References

0 件のコメント:

コメントを投稿