zswang/examplejs

A tool for converting example code into test cases

如何优雅地写测试用例？

背景

做好单元测试是保证代码质量的有效手段。这里介绍一种用示例代码转为测试用例的工具。 这样做可以降低写测试用例的学习和使用成本。

思路

通常在示例代码中我们会用注释给出一个输出预判。

var a = 1;
var b = 2;
console.log(a === b); // false

这样方便复制到控制台编辑运行。

如果写测试用例就会这样：

var a = 1;
var b = 2;
assert.equal(a === b, false);

可以看出来：示例代码和测试代码都有一个输出预判！

那么为何不能用示例代码写测试用例呢？也就是做一下简单的转换即可。

只要做简单的约定就能达到，分别是：

• 示例代码块
• 输出预判
• 异步完成
• 异常预判

方法

定义示例代码块

jsdoc 中用 @example 标记，例如：

/**
 * @example xxyy
 * var a = 1;
 * var b = 2;
 * console.log(a === b); // false
 */

但这种每行都有 * 的代码，复制粘贴后还需要清理一次，所以我倾向于这种:

/**
 * @example xxyy
  var a = 1;
  var b = 2;
  console.log(a === b); // false
 */

为区分运行环境，所以得指定语言，如：

/**
 * @example xxyy
  ```js
  var a = 1;
  var b = 2;
  console.log(a === b); // false
  ```
 */

约定

输出预判

/**
 * @example 表达式相等预判
  ```js
  var a = 1;
  var b = 2;
  console.log(a === b);
  // > false
  ```
 */

/**
 * @example 表达式结果预判
  ```js
  var a = 1;
  var b = 2;
  console.log(a + b);
  // > 3
  ```
 */


/*
 * @example 表达式类型预判
  ```js
  var a = 1;
  console.log(JSON.stringify(a + '1'));
  // > "11"
  ```
 */

批量输出预判

/*
 * @example 批量表达式预判
  ```js
  for (var i = 0; i < 5; i++) {
    console.log(i);
  }
  // > 0
  // > 1
  // > 2
  // > 3
  // > 4
  ```
 */

异步完成

/*
 * @example 异步执行预判
  ```js
  var a = 1;
  setTimeout(function () {
    console.log(a);
    // > 2
    // * done
  }, 1000);
  a++;
  ```
 */

异常预判

/*
 * @example 异常执行预判
  ```js
  var a = JSON.parse('#error');
  // * throw
  ```
*/

浏览器环境

/*
 * @example 浏览器环境
  ```html
  <div></div>
  ```
  ```js
  console.log(document.querySelector('div') !== null);
  // > true
  ```
 */

jQuery

/*
 * @example jQuery
   ```css
   .red {
     background-color: red;
   }
   ```
   ```html
   <div class="red"></div>
   <script src="https://code.jquery.com/jquery-3.1.0.min.js"></script>
   ```
   ```js
   $(function () {
     console.log($('.red').css('background-color'));
     // > red
     // * done
   })
   ```
 */

使用方法

安装

$ npm install examplejs -g

运行

$ examplejs main.js -o test/main.test.js

Gulp

var examplejs = require('gulp-examplejs');

gulp.task('example-js', function() {
  return gulp.src('src/**.js')
    .pipe(examplejs({
      head: 'head.js'
    }))
    .pipe(gulp.dest('test'));
});

License

MIT © zswang

examplejs's Issues

0.1.0

/**
 * @example dom 操作测试
 *
  ` ` `html
    <div></div>
  ` ` `  
  ` ` `css
  div {
    color: red;
  }
  ` ` `  
  ` ` `js
  console.log(document.body.innerHTML);
  // <div></div>  
  document.querySelector('div').innerHTML = 'ok';
  console.log(document.body.innerHTML);
  // <div>ok</div>
  ` ` `
 */

/\s*\*?\s*@example\s*(.*)\n(\s*```(?:javascript|js|css|html)\s*\n([^]*?)\s*```)+/ig

phpunit

/**
 *
 * @example test1
   ```php
   <?php
   $a = 1;
   echo "hello $1";
   // > hello 1
   ```
 */

<?php
class Test1 extends PHPUnit_Framework_TestCase
{
    // ...

    /**
     * @test test1
     */
    public function test1()
    {
        $a = 1;
        $this->assertEquals("hello $1", 'hello 1');
    }

    // ...
}