(翻译)D.O.H: Dojo Objective Harness I

原文来自 http://dojotoolkit.org/reference-guide/util/doh.html

Overview

Usually when people think of a scripting language, it’s often in context of ease of use, simple syntax, and something those without traditional computer science educations can grasp and use. JavaScript unfortunately falls into this category. For a scripting language, though, is difficult to fully master. Making it worse are the environments that execute JavaScript; the infamous Web Browser. For example, Safari works similar to, but not quite the same as Mozilla FireFox, Opera, and even Google Chrome. When Internet Explorer enters the picture, it gets even more complicated as many JavaScript constructs (and DOM functions) that work in all the other browsers will not work in Internet Explorer. This becomes a Testing Nightmare. In fact, I’m sure the frustration of testing JavaScript has caused many an utterance of ‘doh!’ and other less ahem, polite phrases. So ... what can be done about this?

概要

通常人们想到用于脚本编程的语言时，常常会认为它易于使用，语法见大，其中一些即使没有受过传统计算机科学教育也可以明白和使用。很不幸Javascript被归入了这一类语言，但就脚本语言而言，它又难以掌握。执行Javascript的环境，尤其是那些臭名昭著的Web浏览器又让这个语言变得更糟糕。例如，Safari的渲染结果和Mozilla，Firefox类似，但不完一模一样，即便和Chrome相比也不同。加入IE后将会变得更复杂，很多在其他浏览器能运行的Javscript构造方法和DOM函数在IE下都不能运行。这将是测试的噩梦。事实上，我十分确信测试Javascript所带来的挫折已经引发了很多doh的及其他ahem, polite phrases。所以，为此能做些什么？

Enter D.O.H. The Dojo Objective Harness.

选择D.O.H Dojo基于对象的约束?

Just to get it out of the way ... D.O.H. is both an acronym of Dojo Objective Harness and a play on the now commonplace expression of frustration ‘DOH!’. But aside from the very silly name it is a unit test framework developed by the Dojo Toolkit Community (primarily by Alex Russell), in an attempt to solve the complexities of testing JavaScript. For example, in JavaScript, the use of XHR to request remote data asynchronously is commonplace ... and yet few Unit Test frameworks provided any mechanism by which to actually be able test asynchronous functions. Furthermore, most Unit Test Frameworks end up with specific dependencies on certain browsers or runtime environments. Again, D.O.H. tries not to limit itself in this manner, it’s both flexible, extendable, and runs in many environments from browsers to JS runtime environments such as Rhino.

为了解决这个问题,D.O.H不仅是Dojo Objective Harness的缩写，也是一个常见的用于表示受挫的语气词。抛开这个有点傻气的名字，这其实是一个由Dojo Toolkit Community开发的单元测试框架（主要开发人员是Alex Russell），尝试解决测试Javsscript的复杂性。例如Javascript中，使用XHR异步请求服务端数据是非常常见的需求，但很少Unit Test框架能提供一些测试异步函数的方法。还有就是大部分Unit Test框架都会一定的依赖性，如特定浏览器或运行环境。D.O.H将不会受此限制，它相当灵活，易于扩展，能在多种环境中运行，即从浏览器到像Rhino这样的JS运行环境

It’s main purpose is a framework for developers (both dojo committers and others), to unit test out JavaScript functions and custom widgets. Its goal isn’t so much as a way to test a full-blown web application as it is to test the parts that make up the applications in a cross-browser (and even non-browser), compatible manner. By having a good set of unit tests, developers can feel confident that code changes they later make do not cause regressions in existing functions.

D.O.H的主要目的是向开发者提供一个框架（同时面向dojo提交者和其他开发人员），用于Javascript函数及自定义Widget的单元测试。它的目标不是用于全方面测试web应用，而是测试应用某个功能在跨浏览器（甚至没有浏览器）时有一致的结果。只有维护了一个可观的单元测试集，开发者才会对最近代码变更抱有信心，认为这些变更不会对现有功能造成负面影响。

For a quick list of the features of D.O.H. see below:

    * Support for many browsers:

        * Firefox 2, 3, 3.5, 3.6 and 4
        * Safari 3.x, 4.x and 5.x
        * Internet Explorer 6, 7, 8 and 9
        * Google Chrome All versions
        * Opera 9.x and 10.x
        * <and others!>

    * Support for Non-Browser environments, such as Rhino.
    * Modular loading of unit test files.
    * Asynchronous test support (such as testing functions that ultimately use XHR)
    * A simple browser-based graphical front end and runner file.
    * Standard Unit Test Support (assertTrue, assertFalse, assertEqual, timeouts, etcera)
    * Performance tests with basic statistical computations.
    * Java Applet (DOH Robot), for simulating user interaction to test browser input events.
    * If present, will use the Dojo Module Loader to load test files.
    * The ability to load separate HTML pages into an iframe, where the iframe contains a DOH instance and register tests. This allows D.O.H. to test HTML widgets in a separate frame from the D.O.H. framework, which avoids cross-contamination.

快速浏览D.O.H功能特性：

* 支持大量浏览器
* 支持非浏览器环境
* 基于模块加载单元测试文件
* 支持异步测试(尤其是那些最终使用XHR的测试函数)
* 一个基于浏览器的简易图形界面和执行文件
* 支持标准单元测试(assertTrue, assertFalse, assertEqual, timeouts等)
* 含有基础统计计算的性能测试
* Java Applet (DOH机器人)，用于模拟用户交互行为以测试浏览器输入事件
* 目前为止，将使用Dojo模块加载机制加载测试文件
* 能够将一个单独的HTML页面加载到iframe中，这个iframe中有一个DOH的实例及注册的测试。这允许D.O.H在一个单独的基于D.O.H框架的frame测试HTML Widget，而避免相互污染。

Structure

D.O.H. resides in the utils project of the dojo toolkit. Users can find it explicitly at: utils/doh. The following files structure shows the files important to the usage of the framework:

    * utils
          o doh
                + runner.js: The main JavaScript file that defines environment agnostic DOH APIs.
                + _browserRunner.js: An additional JavaScript file that augments the objects defined by runner.js to execute in a browser environment.
                + _rhinoRunner.js: An additional JavaScript file that augments the objects defined by runner.js to execute in the rhino environment.
                + runner.html: HTML bootstrap file used to load D.O.H. in the browser and execute tests.
                + runner.sh: UNIX shell script to launch D.O.H. under Rhino.
                + Robot.html: HTML file used to bootstrap in the DOH Robot for tests that require synthetic user input.
                + LICENSE: The license that governs D.O.H.

 

目录结构

 

D.O.H存于dojo toolkit的utils目录下。用户可以通过/utils/doh直接找到。下面的文件目录显示每个文件在使用框架中的重要性

 

utils

 - doh

   - runner.js 含有DOH的API的环境的主要Javscript文件

   - _browserRunner.js 一个附加的Javascript文件，使用runner.js中的参数在浏览器环境中执行

   - _rhinoRunner.js 一个附加的Javascript文件，使用runner.js中的参数在rhino环境中执行

   - runner.html HTML启动文件，用于载入D.O.H到浏览器并执行测试

   - runner.sh UNIX shell脚本，在Rhnio下启动D.O.H

   - Robot.thml 用于启动DOH机器人的HTML文件，以测试需要结合用户输入的测试

   - LICENSE D.O.H的版权

 

That’s great, but how do I use it?

Okay, that’s wonderful! It’s a unit test environment that’s flexible. So ... how the heck does someone use it? Well, lets start small. The first thing we can do is look at using the browser runner to run a small set of unit tests in dojo. This is done just by loading runner.html in a web browser. What runner.html does is load runner.js and _browserRunner.js. This defines a global object, ‘doh’, that has numerous test registration and assertion functions that can be used by unit tests. Runner.html also does something else, if no module URL was provided for it to load tests from, the runner.html will automatically load the file: dojo/tests/module.js. All that file does is use the dojo module loading system to load in all the test files for core dojo. It then just executes all the currently registered tests and displays the results in the browser.

 

很好的工具，怎么使用？

 

这太美妙了！这是一个非常灵活的单元测试环境。所以。。。该如何使用呢？先从简单做起。首先我们可以看看如何使用浏览器运行器运行一个用dojo写的单元测试集。只需要在web浏览器中载入一个runner.html就能完成。而runner.html负责的是载入runner.js和_browserRunner.js。doh是一个定义好的全局变量，已经注册了很多测试和断言函数，这些都能在单元测试中使用。Runner.html将自动载入文件 dojo/tests/module.js。所有的文件都通过dojo core所提供的dojo模块加载机制载入全部测试文件。然后它将执行所有当前注册的测试用例并将其测试结果在浏览器显示

Okay, so starting up DOH is as simple as running runner.html ... but now you may be asking how do I load my tests? Simple! You pass it as a query parameter to the runner,html. For example, say you just want to run the dojo.date tests, you would load the following in your browser: util/doh/runner.html?testModule=tests.date What this does is instruct the runner to look in dojo/tests and load the date.js file. Please note here that you do not have to put your unit tests in dojo/tests! The browser runner just has a default search path to look in dojo/ for a module in addition to looking at the assumed path of tests/date.js.

 

启动DOH和运行runner.html一样简单...不过现在你也会会问如何载入我的测试用例？简单！只需要将其作为查询参数传给runner.html。例如：你想测试dojo.date,就在浏览器中运行下列代码: util/doh/runner.html?testModule=tests.date. 其中运行器将在dojo.tests目录中载入date.js文件。请留意你没有必要将你的单元测试放在dojo/tests下!浏览器运行器只是会将dojo/作为默认模块查找路径，并查找到了tests/date.js(????)

What most developers do is define their own tests in their module’s directory under tests/. you can see this as a common pattern in dojox. For example, dojox/data/tests have all the dojox.data unit tests. You can also note that dojox/data/tests has a runTests.html. All that runTests.html does is redirect back to util/doh/runner.html and set the testModule parameter. It’s a simple helper file that module owners use to quick-launch their unit tests.

 

大部分开发者都会tests下定义自己的模块以及测试。你会发现dojox也采用了相同的模式, dojox/data/tests下是所有dojox.data的单元测试。你也会发现 dojox/data/tests下有一个runTests.html. 所有的这些runTests.html将重定向到util/doh/runner.html并设置参数testModule的值。对于模块所有者而言，这是一个简易的辅助工具用于快速启动他们的单元测试

 

What is a test module?

Okay, whee! The runner.html can be told what test module to load. So ... what the heck is a test module!? A test module is nothing more than a file that requires in more test files, calls doh.register() to register tests, or a combination of both. Basically a module is nothing more than the file that calls the doh functions to register tests before D.O.H. executes the test run. For example, the following code snippet is a test module:

 

什么是测试模块

 

通常会通过runner.html载入那个测试模块。所以，what the heck is a test module?一个测试模块无非就是一个需要加载更多测试文件的文件，可以调用doh.register()注册测试用例或者组合使用。一般来说，一个模块只是一个在D.O.Hz执行测试用例前，调用doh函数注册测试用例的文件。例如下面的代码片段就是一个测试模块

 

Example Test Module: Simple test registration

 

//Declare out the name of the test module to make dojo's module loader happy.
dojo.provide("my.test.module");

doh.register("MyTests", [
  function assertTrueTest(){
    doh.assertTrue(true);
    doh.assertTrue(1);
    doh.assertTrue(!false);
  },
  {
    name: "thingerTest",
    setUp: function(){
      this.thingerToTest = new Thinger();
      this.thingerToTest.doStuffToInit();
    },
    runTest: function(){
      doh.assertEqual("blah", this.thingerToTest.blahProp);
      doh.assertFalse(this.thingerToTest.falseProp);
      // ...
    },
    tearDown: function(){
    }
  },
  // ...
]);

 

Example Test Module: Module that loads other modules

 

//Declare out the name of the test module to make dojo's module loader happy.
dojo.provide("my.test.module2");

//Require in the separate files that implement and register all the tests.
dojo.require("my.test.widget.Foo0");
dojo.require("my.test.widget.Foo1");
dojo.require("my.test.widget.Foo2");

 

Notes on Registering Tests¶

    * Names of functions or of test fixtures must be unique per test group. D.O.H. records results by using the name as a hash key on the results objects.

 

注册测试用例的注意事项

 

* 每个函数的名字或者测试fixture在每个测试组里都必须唯一。 D.O.H 通过一个把名字作为哈希值的结果对象记录结果。