Programming DSL: Implements JSpec

https://codingstyle.cn/topics/80
https://github.com/horance-liu/jspec

本文通过「JSpec」的设计和实现的过程，加深认识「内部DSL」设计的基本思路。JSpec是使用Java8实现的一个简单的「BDD」测试框架。

Given-When-Then

经过实践证明，基于场景验收的Given-When-Then命名风格具有强大的表现力。但JUnit遵循严格的标示符命名规则，程序员需要承受巨大的痛苦。

这种混杂「驼峰」和「下划线」的命名风格，虽然在社区中得到了广泛的应用，但在重命名时，变得非常不方便。

public class GivenAStack {
  @Test
  public void should_be_empty_when_created() { 
  }

  @Test
  public void should_pop_the_last_element_pushed_onto_the_stack() { 
  }
}

以RSpec, Cucumber, Jasmine等为代表的[BDD」(Behavior-Driven Development)测试框架以强大的表现力，迅速得到了社区的广泛应用。其中，RSpec, Jasmine就是我较为喜爱的测试框架。例如，Jasmine的JavaScript测试用例是这样的。

describe("A suite", function() {
  it("contains spec with an expectation", function() {
    expect(true).toBe(true);
  });
});

我们将尝试设计和实现一个Java版的BDD测试框架：JSpec。它的风格与Jasmine基本类似，并与Junit4配合得完美无瑕。

@RunWith(JSpec.class)
public class JSpecs {{
  describe("A spec", () -> {
    List<String> items = new ArrayList<>();

    before(() -> {
      items.add("foo");
      items.add("bar");
    });

    after(() -> {
      items.clear();
    });

    it("runs the before() blocks", () -> {
      assertThat(items, contains("foo", "bar"));
    });

    describe("when nested", () -> {
      before(() -> {
        items.add("baz");
      });

      it("runs before and after from inner and outer scopes", () -> {
        assertThat(items, contains("foo", "bar", "baz"));
      });
    });
  });
}}

初始化块

public class JSpecs {{
  ......
}}

嵌套两层{}，这是Java的一种特殊的初始化方法，常称为初始化块。其行为与如下代码类同，但它更加简洁、漂亮。

public class JSpecs {
  public JSpecs() {
    ......
  }
}

代码块

describe, it, before, after都存在一个() -> {...}代码块，以便实现行为的定制化，为此先抽象一个Block的概念。

@FunctionalInterface
public interface Block {
  void apply() throws Throwable;
}

雏形

定义如下几个函数，明确JSpec DSL的基本雏形。

public class JSpec {
  public static void describe(String desc, Block block) {
    ......
  }

  public static void it(String behavior, Block block) {
    ......
  }

  public static void before(Block block) {
    ......
  }

  public static void after(Block block) {
    ......
  }

上下文

describe可以嵌套describe, it, before, after的代码块，并且外层的describe给内嵌的代码块建立了「上下文」环境。

例如，items在最外层的describe中定义，它对describe整个内部都可见。

隐式树

describe可以嵌套describe，并且describe为内部的结构建立「上下文」，因此describe之间建立了一棵「隐式树」。

领域模型

为此，抽象出了Context的概念，用于描述describe的运行时。也就是是，Context描述了describe内部可见的几个重要实体：

• List<Block> befores：before代码块集合
• List<Block> afters：after代码块集合
• Description desc：包含了父子之间的层次关系等上下文描述信息
• Deque<Executor> executors：执行器的集合。

Executor在后文介绍，可以将Executor理解为Context及其Spec的运行时行为；其中，Context对于于desribe子句，Spec对于于it子句。

因为describe之间存在「隐式树」的关系，Context及Spec之间也就形成了「隐式树」的关系。

参考实现

public class Context {

  private List<Block> befores = new ArrayList<>();
  private List<Block> afters = new ArrayList<>();

  private Deque<Executor> executors = new ArrayDeque<>();
  private Description desc;

  public Context(Description desc) {
    this.desc = desc;
  }

  public void addChild(Context child) {
    desc.addChild(child.desc);
    executors.add(child);

    child.addBefore(collect(befores));
    child.addAfter(collect(afters));
  }

  public void addBefore(Block block) {
    befores.add(block);
  }

  public void addAfter(Block block) {
    afters.add(block);
  }

  public void addSpec(String behavior, Block block) {
    Description spec = createTestDescription(desc.getClassName(), behavior);
    desc.addChild(spec);
    addExecutor(spec, block);
  }

  private void addExecutor(Description desc, Block block) {
    Spec spec = new Spec(desc, blocksInContext(block));
    executors.add(spec);
  }

  private Block blocksInContext(Block block) {
    return collect(collect(befores), block, collect(afters));
  }
}

实现addChild

describe嵌套describe时，通过addChild完成了两件重要工作：

• 「子Context」向「父Context」的注册；也就是说，Context之间形成了「树」形结构；
• 控制父Context中的before/after的代码块集合对子Context的可见性；

public void addChild(Context child) {
  desc.addChild(child.desc);
  executors.add(child);

  child.addBefore(collect(befores));
  child.addAfter(collect(afters));
}

其中，collect定义于Block接口中，完成before/after代码块「集合」的迭代处理。这类似于OO世界中的「组合模式」，它们代表了一种隐式的「树状结构」。

public interface Block {
  void apply() throws Throwable;

  static Block collect(Iterable<? extends Block> blocks) {
    return () -> {
      for (Block b : blocks) {
        b.apply();
      }
    };
  }
}

实现addExecutor

其中，Executor存在两种情况:

• Spec: 使用it定义的用例的代码块
• Context: 使用describe定义上下文。

为此，addExecutor被addSpec, addChild所调用。addExecutor调用时，将Spec注册到Executor集合中，并定义了Spec的「执行规则」。

private void addExecutor(Description desc, Block block) {
    Spec spec = new Spec(desc, blocksInContext(block));
    executors.add(spec);
  }

  private Block blocksInContext(Block block) {
    return collect(collect(befores), block, collect(afters));
  }

blocksInContext将it的「执行序列」行为固化。

• 首先执行before代码块集合；
• 然后执行it代码块；
• 最后执行after代码块集合；

抽象Executor

之前谈过，Executor存在两种情况:

• Spec: 使用it定义的用例的代码块
• Context: 使用describe定义上下文。

也就是说，Executor构成了一棵「树状」的数据结构；it扮演了「叶子节点」的角色；Context扮演了「非叶子节点」的角色。为此，Executor的设计采用了「组合模式」。

import org.junit.runner.notification.RunNotifier;

@FunctionalInterface
public interface Executor {
  void exec(RunNotifier notifier);
}

叶子节点：Spec

Spec完成对it行为的封装，当exec时完成it代码块() -> {...}的调用。

public class Spec implements Executor {

  public Spec(Description desc, Block block) {
    this.desc = desc;
    this.block = block;
  }

  @Override
  public void exec(RunNotifier notifier) {
    notifier.fireTestStarted(desc);
    runSpec(notifier);
    notifier.fireTestFinished(desc);
  }

  private void runSpec(RunNotifier notifier) {
    try {
      block.apply();
    } catch (Throwable t) {
      notifier.fireTestFailure(new Failure(desc, t));
    }
  }

  private Description desc;
  private Block block;
}

非叶子节点：Context

public class Context implements Executor {
  ......

  private Description desc;

  @Override
  public void exec(RunNotifier notifier) {
    for (Executor e : executors) {
      e.exec(notifier);
    }
  }
}

实现DSL

有了Context的领域模型的基础，DSL的实现变得简单了。

public class JSpec {
  private static Deque<Context> ctxts = new ArrayDeque<Context>();

  public static void describe(String desc, Block block) {
    Context ctxt = new Context(createSuiteDescription(desc));
    enterCtxt(ctxt, block);
  }

  public static void it(String behavior, Block block) {
    currentCtxt().addSpec(behavior, block);
  }

  public static void before(Block block) {
    currentCtxt().addBefore(block);
  }

  public static void after(Block block) {
    currentCtxt().addAfter(block);
  }

  private static void enterCtxt(Context ctxt, Block block) {
    currentCtxt().addChild(ctxt);
    applyBlock(ctxt, block);
  }

  private static void applyBlock(Context ctxt, Block block) {
    ctxts.push(ctxt);
    doApplyBlock(block);
    ctxts.pop();
  }

  private static void doApplyBlock(Block block) {
    try {
      block.apply();
    } catch (Throwable e) {
      it("happen to an error", failing(e));
    }
  }

  private static Context currentCtxt() {
    return ctxts.peek();
  }
}

上下文切换

但为了控制Context之间的「树型关系」(即describe的嵌套关系)，为此建立了一个Stack的机制，保证运行时在某一个时刻Context的唯一性。

只有describe的调用会开启「上下文的建立」，并完成上下文「父子关系」的链接。其余操作，例如it, before, after都是在当前上下文进行「元信息」的注册。

虚拟的根结点

使用静态初始化块，完成「虚拟根结点」的注册；也就是说，在运行时初始化时，栈中已存在唯一的Context("JSpec: All Specs")虚拟根节点。

public class JSpec {
  private static Deque<Context> ctxts = new ArrayDeque<Context>();

  static {
    ctxts.push(new Context(createSuiteDescription("JSpec: All Specs")));
  }

  ......
}

运行器

为了配合JUnit框架将JSpec运行起来，需要定制一个JUnit的Runner。

public class JSpec extends Runner {
  private Description desc;
  private Context root;

  public JSpec(Class<?> suite) {
    desc = createSuiteDescription(suite);
    root = new Context(desc);
    enterCtxt(root, reflect(suite));
  }

  @Override
  public Description getDescription() {
    return desc;
  }

  @Override
  public void run(RunNotifier notifier) {
    root.exec(notifier);
  }

  ......
}

在编写用例时，使用@RunWith(JSpec.class)注解，告诉JUnit定制化了运行器的行为。

@RunWith(JSpec.class)
public class JSpecs {{
  ......
}}

在之前已讨论过，JSpec的run无非就是将「以树形组织的」Executor集合调度起来。

实现reflect

JUnit在运行时，首先看到了@RunWith(JSpec.class)注解，然后反射调用JSpec的构造函数。

public JSpec(Class<?> suite) {
  desc = createSuiteDescription(suite);
  root = new Context(desc);
  enterCtxt(root, reflect(suite));
}

通过Block.reflect的工厂方法，将开始执行测试用例集的「初始化块」。

public interface Block {
  void apply() throws Throwable;

  static Block reflect(Class<?> c) {
    return () -> {
      Constructor<?> cons = c.getDeclaredConstructor();
      cons.setAccessible(true);
      cons.newInstance();
    };
  }
}

此刻，被@RunWith(JSpec.class)注解标注的「初始化块」被执行。

@RunWith(JSpec.class)
public class JSpecs {{
  ......
}}

在「初始化块」中顺序完成对describe, it, before, after等子句的调用，其中：

• describe开辟新的Context；
• describe可以递归地调用内部嵌套的describe；
• describe调用it, before, after时，将信息注册到了Context中；
• 最终Runner.run将Executor集合按照「树」的组织方式调度起来；