开发 Discourse 插件 - 第 6 部分 - 添加验收测试

上一篇教程:Developing Discourse Plugins - Part 5 - Add an admin interface


你知道吗?Discourse 拥有两套庞大的代码库测试套件。在服务器端,我们的 Ruby 代码使用 rspec 进行测试套件运行。对于浏览器端应用,我们有一套包含 ember-testingqunit 测试套件。

假设你已经搭建好了开发环境,访问 http://localhost:3000/tests URL 即可在浏览器中启动 JavaScript 测试套件。一个有趣的功能是,你可以在右下角的微型窗口中看到测试正在对应用进行测试的过程:

Discourse 应用构建了大量的测试,当你访问 /tests URL 时,这些测试就会开始运行。因此,按你正在开发的插件来过滤测试可能会很有帮助。你可以在界面中点击 Plugin(插件)下拉菜单并选择你的插件来实现这一点:

在插件中添加验收测试

首先,确保你检出的是最新版本的 Discourse。能够从插件中运行验收测试是一个相对较新的功能,如果你没有检出最新版本,你的测试将不会显示出来。

在本文中,我将为我们在本系列的 第 5 部分 中创建的 purple-tentacle 插件编写一个验收测试。

添加验收测试就像向你的插件中添加一个文件一样简单。创建以下文件:

test/javascripts/acceptance/purple-tentacle-test.js

import { acceptance, exists } from "discourse/tests/helpers/qunit-helpers";
import { click, visit } from "@ember/test-helpers";
import { test } from "qunit";

acceptance("Purple Tentacle", function (needs) {
  needs.settings({ purple_tentacle_enabled: true });
  needs.user();

  test("Purple tentacle button works", async function (assert) {
    await visit("/admin/plugins/purple-tentacle");
    assert.ok(exists("#show-tentacle"), "it shows the purple tentacle button");
    assert.ok(!exists(".tentacle"), "the tentacle is not shown yet");
    await click("#show-tentacle");
    assert.ok(exists(".tentacle"), "the tentacle wants to rule the world!");
  });
});

我尽量让测试代码清晰易懂,但如果你以前从未写过验收测试,可能会觉得有点困惑。我强烈建议你 阅读 Ember 文档 中关于验收测试的部分,那里有很多很棒的信息。

在我们要编写的每个测试中,都需要对某些内容进行 assert(断言)。在我们的测试中,我们要进行一些断言,以检查触手(tentacle)是否最初是隐藏的,以及在单击按钮后才显示出来。

我们希望在做出断言之前定义一系列要执行的操作。为此,我们使用 await 关键字。通过使用该关键字,我们会等待每个异步辅助函数执行完毕。

我们第一个重要的操作是:await visit("/admin/plugins/purple-tentacle");。这告诉我们的测试在应用中导航到该 URL。该 URL 正是显示触手的页面。

在访问显示紫色触手按钮的页面后,我们想检查页面上是否存在该按钮,以及触手图像是否尚不存在。

这是通过以下断言完成的:

assert.ok(exists("#show-tentacle"), "it shows the purple tentacle button");
assert.ok(!exists(".tentacle"), "the tentacle is not shown yet");

注: 之前版本的 purple-tentacle 插件在 handlebars 模板中没有 #show-tentacle 元素 ID。请查看最新版本以跟随本文操作!

一旦这些测试通过,就该测试交互功能了。

下一个命令是 await click('#show-tentacle');,它告诉我们的测试框架我们要单击该按钮以显示触手。

模拟单击按钮后,我们可以通过断言来检查触手是否出现:

assert.ok(exists(".tentacle"), "the tentacle wants to rule the world!");

还不错吧?你可以在开发机器上访问 http://localhost:3000/tests?qunit_single_plugin=purple-tentacle&qunit_skip_core=1 来亲自尝试这个测试。你应该会很快看到紫色触手出现,并且所有测试都会通过。

如果你想使用 PhantomJS 在命令行上运行插件的 qunit 测试,可以运行

rake plugin:qunit['purple-tentacle']

(其中 purple-tentacle 是你的插件的文件夹名称)

调试你的测试

在编写插件时,测试可以帮助你识别插件中的问题。在开发测试或更改插件代码时,测试可能会失败。为了帮助理解原因,Ember 提供了一些不错的辅助函数:pauseTest()resumeTest()

要使用它们,请在你想要测试暂停的代码位置添加 await pauseTest()。现在,当你在浏览器中运行测试时,测试会在你添加 pauseTest() 的地方自动暂停。这将给你一个检查页面或查看任何错误以帮助调试问题的机会。

接下来去哪里

我不想显得像坏掉的唱片,但 Ember 文档 中关于测试的部分非常出色。你也可以通过浏览我们 javascript 测试目录 中的测试,看看 Discourse 如何测试各种功能。那里有很多例子你可以从中学习。

祝你测试愉快!


系列更多内容

第 1 部分:插件基础
第 2 部分:插件出口
第 3 部分:站点设置
第 4 部分:git 设置
第 5 部分:管理界面
第 6 部分:本文
第 7 部分:发布你的插件


本文档受版本控制 - 建议在 github 上提出更改。

30 个赞

OMG, have I put off writing tests for this long?!

A few things
I noticed you put an “id” into the template file that wasn’t there in the previous tutorial
I added 3 more tests to deal with the “Hide Tentacle” button I added
I needed to be logged in it is an Admin page
I needed to use port 4000 for my VirtualBox Vagrant set-up

Happily, quick success !

5 个赞

I’ve noticed a push to implement testing for plugins lately and I completely agree that this is important. I’ve been terrible at writing these in the past and want to get caught up.

I was considering the setup of Travis CI on a plugin repo as I noticed the ability to use Docker with Travis. But having never touched Travis before, is it possible to do this with a plugin? It would be nice to submit PRs to my own repo and have the tests run automatically.

5 个赞

how can I run single ember tests on the browser?

http://localhost:3000/qunit?module=Acceptance%3A%20Purple%20Tentacle

I mean, if I have another acceptance test called “another test”, how would I run it? Thank you!

If you click “rerun” beside a test, you’ll get a URL that is just for that particular test that you can refresh over and over.

You can also run by module by clicking in the “All Module” box and checking off just the modules you want to run.

2 个赞

This tutorial needs updating to replace ok(...) with assert.ok(...).

Have put the necessary changes in a PR - I’m happy to edit the OP if it’s made into a wiki :slight_smile:

https://github.com/eviltrout/purple-tentacle/pull/2

2 个赞

OK it is wikified! PM me if anything else needs this treatment any time.

1 个赞

A note after writing some basic acceptance tests for the Elections Plugin:

  • If you use the default loggedIn option, you’re logged in as eviltrout with the properties in this session fixture

  • You can login as a custom user (necessary if you’ve added custom user properties) by defining your own session fixture and setting it as the current user using the beforeEach hook. See here for an example.

@eviltrout is there a better way of using a custom user for acceptance tests?

5 个赞

What we should probably do is change the acceptance method in discourse to take an argument for the user to log in as. Then your test could say { loggedIn: true, logInAs: angus }

If you’ve got time for that PR we’d accept it!

4 个赞

q: how to run the ruby tests tests for a plugin?

i am trying to run the tests for discourse-github-linkback, but i have no idea how.

After some stackoverflow i tried this (and i got some errors):

~/discourse$ bundle exec rspec ./plugins/discourse-github-linkback/spec/lib/github_linkback_spec.rb 

An error occurred while loading ./plugins/discourse-github-linkback/spec/lib/github_linkback_spec.rb.
Failure/Error: CoreExt::ActiveSupport.without_bootsnap_cache { super }

NameError:
  uninitialized constant GithubLinkback
# ./plugins/discourse-github-linkback/spec/lib/github_linkback_spec.rb:3:in `<top (required)>'
# ------------------
# --- Caused by: ---
# NameError:
#   uninitialized constant GithubLinkback
#   ./plugins/discourse-github-linkback/spec/lib/github_linkback_spec.rb:3:in `<top (required)>'
No examples found.

Randomized with seed 60987


Finished in 0.02025 seconds (files took 3.36 seconds to load)
0 examples, 0 failures, 1 error occurred outside of examples

Randomized with seed 60987

Note that i see the plugin in the local discourse dev admin page, so i hope it is correctly installed (into ~discourse/plugins/

Simplest way, run bin/rake autospec, and save the file

1 个赞

From what i see, doing cd ~/discourse and then running

runs all the tests for discourse.

On my ubuntu 18.04 VM with i5 6500, this has been running for half an hour already.
It feels wrong to run the whole tests suite when i only want to run the tests in that one plugin.
(this is especially so when i probably will modify my tests again, at least a few times)

Did i do something wrong?

Let me guess, you are symlinking your plugin vs checking out directly to the path under plugins

no,

tbp@tbp-linux-dev:~$ cd ~/discourse/plugins/
git clone -b allow-all-user-repositories-wildcard https://github.com/TheBestPessimist/discourse-github-linkback
tbp@tbp-linux-dev:~/discourse/plugins$ ll
total 40
drwxr-xr-x 10 tbp tbp 4096 May 13 21:48 ./
drwxr-xr-x 20 tbp tbp 4096 May 13 21:18 ../
drwxr-xr-x  6 tbp tbp 4096 May 13 20:29 discourse-details/
drwxr-xr-x  6 tbp tbp 4096 May 13 21:48 discourse-github-linkback/
drwxr-xr-x  6 tbp tbp 4096 May 13 20:29 discourse-local-dates/
drwxr-xr-x  9 tbp tbp 4096 May 13 20:29 discourse-narrative-bot/
drwxr-xr-x  7 tbp tbp 4096 May 13 20:29 discourse-nginx-performance-report/
drwxr-xr-x  5 tbp tbp 4096 May 13 20:29 discourse-presence/
drwxr-xr-x  3 tbp tbp 4096 May 13 20:29 lazyYT/
drwxr-xr-x  9 tbp tbp 4096 May 13 20:29 poll/
tbp@tbp-linux-dev:~/discourse/plugins$ 

Can you confirm you tried saving the spec file once it was running, cause it is meant to interrupt stuff and start running the plugin spec?

since the initial bin/rake autospec is still running, there was/is no “save spec file” message yet.
also, by running bin/rake autospec --help, i saw no --save option.

I didn’t understand what save the file meant, so my full command was bin/rake autospec > spec.rb ← probably this is wrong

I meant in Vim or whatever you use, save the spec file, there is a watcher on it that will invoke the spec runner once it is saved.

Also see: How do I run only discourse/plugins/poll/spec? - #6 by tgxworld

1 个赞

Finally i did it :^).

With the help of that link, i ran the tests by using this command:
bundle exec rake plugin:spec["discourse-github-linkback"]
and, ofc, i was in ~/discourse when doing that.

Thanks for all your help @sam!

(1st PR for discourse-plugin babyyyyy :tada:)

8 个赞

My Qunit-Tests aren’t executed or at least they don’t show me any output.
They finish with the following:

No output has been received in the last 10m0s, this potentially indicates a stalled build or something wrong with the build itself.
Check the details on how to adjust your build configuration on: https://docs.travis-ci.com/user/common-build-problems/#Build-times-out-because-no-output-was-received

Travis.CI Result - Travis CI
Test-File - GitHub - kokoro-ko/discourse-humble-box: humble-bundle onebox · GitHub

I am not that skilled with CI yet and haven’t found my mistake by now.

Do your tests pass if you visit /qunit on your development environment? How about if you run rake plugin:qunit[discouse-humble-box]?

2 个赞