如何让你的 github 项目更加高大上

5,467 阅读7分钟
原文链接: blog.5udou.cn

前言

昨天把这个博客网站的代码开源放在了github上,然后刚好不巧看到百度EFE写的文章前端开源项目持续集成三剑客,突然想起好多项目的ReadMe文件确实看着很酷炫,有很多的徽章,于是就想着自己博客代码也可以这样做,显得自己高大上(偷笑)。。于是花了一天,写了些单元测试,跑了一下CI,检测了下代码,哗啦啦地就把好多个徽章给加到自己的项目中去了。。最后的效果如图:

1、Travis CI

首先也是最必须的应该是给自己的项目加个持续测试的功能吧,以前刚毕业的时候在第一家公司都没有听过CI着一个概念,后来第二家公司才知道有CI、jenkins之类的概念。后在接触多了发现jenkins还真的很不错,全部自动化测试。但是jenkins只能在局域网下测试呀,有没有工具可以在互联网下进行测试呢?果然,万能的外国人就创造了这么一个能够在互联网下持续集成你的项目,比较火热的有:Travis CICircle CI。我就选择了Travis CI来做我的项目的持续集成。

1.1、Travis操作步骤

  1. 进入官网,使用github账号登录:
  2. 登录成功之后进入到你的账户页面:travis-ci.org/profile/xxx… 之后点击红色框中的按钮,变成绿色之后,点击右边的设置按钮,就可以进入对应项目的CI页面:
  3. 配置package.json文件的scripts字段,添加测试的脚本命令: "test": "./node_modules/.bin/mocha test/setup.js test/test*.js",

  4. 在项目的根目录下添加.travis.yml,以个人项目为例:

    language: node_js
    os:
    - linux
    node_js:
    - 6
    install:
    - npm install -g sails bower cnpm
    - npm i
    script:
    - npm run cover
    after_success:
    - npm run coveralls
    

配置解释:

  1. 配置集成测试的语言范畴,参考Language-specific Guides
  2. 配置测试需要跑的系统环境
  3. 测试开始之前需要安装些什么必备的软件
  4. 测试的脚本
  5. 测试成功之后应该执行的动作,因为我们后面会将coveralls的操作放在CI上,所以这里预先配置好。

1.2、mocha单元测试的配置

Sails官网推荐使用mocha测试框架,官方文档如下:sailsjs.org/documentati…

根据官网的介绍,我们在根目录下新建test文件夹,然后添加mocha.opts以及setup.js两个文件:

mocha.opts

--recursive -R spec  -t 35000

setup.js

'use strict';

var Sails = require('sails');

before(function(done) {
  Sails.lift({
    port: 8989,
    log: {
      noShip: true
    },
    hooks: {
      grunt: false
    },
    models: {
      connection: 'localDiskDb',
      migrate: 'drop'
    }

  }, done);
});


after(function() {
  Sails.lower();
});

配置解释:

  1. 文件mocha.opts文件的作用相当于是将命令的参数直接放到文件中,里面的参数含义是:

    1.1. -R,也就是--reporter参数,用来指定测试报告的格式,默认是spec格式。

    1.2. --recursive,告诉mocha应该测试test下面所有的测试用例不管在哪一层都会执行

    1.3. -t,配置mocha每个测试用例的超时时间,更多配置参考:mochajs.org/

  2. mocha提供了测试的生命周期,所以在setup.js文件中使用before和after来配置整个测试开始前和结束后应该做的事。我们使用Sails.lift这个API启动Sails服务器,并配置一些必须的参数,关于该API的使用可以参考:sailsjs.org/documentati…

1.3、编写你的单元测试

接下去开始写你的单元测试,mocha的单元测试语法可以参考官网,我简单地写了两个测试脚本(很明显测试用例不够,在后面的测试覆盖率会显示比较低的百分比)。唯独需要提醒的一点是:

beforeEach vs before

describe('hooks', function() {

    before(function() {
        // runs before all tests in this block
    });

    after(function() {
        // runs after all tests in this block
    });

    beforeEach(function() {
        // runs before each test in this block
    });

    afterEach(function() {
        // runs after each test in this block
    });

    // test cases
});

所以:

  1. before和after的代码没有特殊顺序要求。
  2. 同一个describe下可以有多个before,执行顺序与代码顺序相同。
  3. 同一个describe下的执行顺序为before, beforeEach, afterEach, after
  4. 当一个it有多个before的时候,执行顺序从最外围的describe的before开始,其余同理
  5. 使用带有Each的钩子是会在每个it语句执行的时候执行一遍,所以编写测试用例的时候如果你的预置条件仅仅是在一个describe下执行一次的话就请使用before。

1.4、上传代码触发CI

测试编写完毕之后,本地跑通过之后就可以上传你的代码,从而触发CI的执行。上传之前记得在你的ReadMe文件下添加你的第一个徽章:

[![Build Status](https://travis-ci.org/linxiaowu66/douMiBlogPlatform.svg?branch=master)](https://travis-ci.org/linxiaowu66/douMiBlogPlatform)

这段文字的获取方法:docs.travis-ci.com/user/status…

之后就可以在Travis CI上看到你的项目编译状态了:

1.5、Tips

如果你的编译状态一直处于build:unknown的时候,可以删除你的项目后重新启用,也就是在刚才图3中那个按钮,先置为灰色再重新置为绿色即可。

2、coveralls

接着我们需要生成一份代码覆盖率的报告,使用的工具是coveralls。做法和travis CI一样,使用你的github账号登录,然后指定你要报告的项目的,这些就不再细说了,唯一一个重要的地方就是获取该项目的token:

登录之后见到这个页面:

之后点击上面的Add Repo,进入下面的页面:

接着将按钮置为ON状态,并点击右边的红色框的detail,进入下面的页面获取token:

2.1、添加.coveralls.yml

在根目录下添加.coverall.yml文件,并添加下面内容:

service_name: travis-ci
repo_token: 91CREHrglvPHyRixRQTOzcAZErWXBuhVS

2.2、生成测试报告

给Coveralls上传的测试报告需要有统一的lcov格式,而mocha需要结合istanbul工具才可以生成这种格式的报告,所以:

  1. cnpm i install istanbul coveralls mocha-lcov-reporter --save-dev
  2. 在package.json文件的scripts字段添加下面这行命令:"cover": "./node_modules/.bin/istanbul cover _mocha"使用_mocha是因为如果调用mocha命令的话,它是用过fork一个子进程_mocha来执行测试,这样就导致istanbul在子进程中无法使用钩子从而默认不会提供覆盖率,所以直接调用_mocha这个进程才能做到。
  3. 在package.json文件的scripts字段继续添加下面这行命令:"coveralls": "npm run cover -- --report lcovonly && cat ./coverage/lcov.info | ./node_modules/.bin/coveralls"注意命令行中一个--,这个表示后面的--report lcovonly是mocha的命令行参数而不是istanbul的!
  4. 配置.travis.yml,内容在上一节已经讲过了。直接跑的npm run cover

2.3、结果展示

代码重新push上去之前在ReadMe文件中再添加一个徽章: [![Coverage Status](https://coveralls.io/repos/github/linxiaowu66/douMiBlogPlatform/badge.svg?branch=master)](https://coveralls.io/github/linxiaowu66/douMiBlogPlatform?branch=master)

徽章的代码获取是在你的项目页面下:

命令行结果:

3、GA&&stability&&Liscence

在添加GA和stability这两个徽章,GA的操作步骤在GA的项目ReadMe文件中写的很详细:github.com/igrigorik/g….

stability则可以直接写到你的ReadMe文件中:

[![Analytics](https://ga-beacon.appspot.com/UA-85522412-2/welcome-page)](https://github.com/igrigorik/ga-beacon)
[![stable](http://badges.github.io/stability-badges/dist/stable.svg)](http://github.com/badges/stability-badges)

License也是类似: [![MIT Licence](https://badges.frapsoft.com/os/mit/mit.svg?v=103)](https://opensource.org/licenses/mit-license.php)

4、bitHound

Nodejs的代码分析工具,非常实用的一个在线code review工具。同理我们使用github账号登录,引入你的项目,在你的项目中新建.bithoundrc文件:

{
  "ignore": [
    "**/node_modules/**",
    "**/vendor/**",
    "**/**-min-**",
    "**/**-min.**",
    "**/**.min.**",
    "**/**jquery.?(ui|effects)-*.*.?(*).?(cs|j)s",
    "**/**jquery-*.*.?(*).?(cs|j)s",
    "bower_components/**",
    "api/response/**",
    "api/servives/**"
  ],
  "test": [
    "**/test/**",
    "**/tests/**",
    "**/spec/**",
    "**/specs/**"
  ]
}

该文件的配置参考:gist.github.com/bithoundio/…

之后你便可以提交代码,bithound会监听你的github项目的变化,从而触发新的代码检测,检测完毕之后便可以在下面的页面找到好多徽章:

于是你又可以在ReadMe 文件中添加下面4个徽章:

[![bitHound Overall Score](https://www.bithound.io/github/linxiaowu66/douMiBlogPlatform/badges/score.svg)](https://www.bithound.io/github/linxiaowu66/douMiBlogPlatform)
[![bitHound Dependencies](https://www.bithound.io/github/linxiaowu66/douMiBlogPlatform/badges/dependencies.svg)](https://www.bithound.io/github/linxiaowu66/douMiBlogPlatform/master/dependencies/npm)
[![bitHound Dev Dependencies](https://www.bithound.io/github/linxiaowu66/douMiBlogPlatform/badges/devDependencies.svg)](https://www.bithound.io/github/linxiaowu66/douMiBlogPlatform/master/dependencies/npm)
[![bitHound Code](https://www.bithound.io/github/linxiaowu66/douMiBlogPlatform/badges/code.svg)](https://www.bithound.io/github/linxiaowu66/douMiBlogPlatform)
[![MIT Licence](https://badges.frapsoft.com/os/mit/mit.svg?v=103)](https://opensource.org/licenses/mit-license.php)

至此目前项目的徽章就添加完毕了,说了这么多并不是说只是单纯地添加这些徽章来酷炫展示,更重要的是提高项目的健壮性,所以对于单元测试不够的或者代码检查有问题的都是需要花心思去修改这些的。同时项目的不同使用的徽章也是不一样的,大家应该选择适合自己项目的。

参考:

  1. efe.baidu.com/blog/front-…
  2. www.imooc.com/article/det…
  3. blog.csdn.net/u011192270/…