Discourseプラグイン開発 - 第6回 - 受け入れテストの追加

前回のチュートリアル: Developing Discourse Plugins - Part 5 - Add an admin interface


Discourseには、コードベース用の2つの大規模なテストスイートが存在することをご存知ですか? サーバー側では、Rubyコードが rspec を使用したテストスイートを備えています。ブラウザアプリケーションでは、ember-testing を含む qunit スイートがあります。

開発環境がセットアップされていると仮定すると、http://localhost:3000/tests URLにアクセスすると、ブラウザでJavaScriptテストスイートの実行が始まります。楽しい機能の1つとして、右下隅のミニチュアウィンドウでアプリケーションがテストされている様子を見ることができます。

Discourseアプリケーションは、/tests URLにアクセスすると実行が始まる大量のテストを含んで構築されています。したがって、作業中のプラグインでテストを絞り込むと便利です。インターフェースで Plugin ドロップダウンをクリックし、自分のプラグインを選択することでそれを行うことができます。

プラグインへの受け入れテストの追加

まず、Discourseの最新バージョンをチェックアウトしていることを確認してください。プラグインから受け入れテストを実行できるのは比較的新しい機能であり、最新バージョンをチェックアウトしていない場合、テストが表示されません。

この記事では、このシリーズのパート5で作成した purple-tentacle プラグインの受け入れテストを記載します。

受け入れテストの追加は、プラグインにファイルを1つ追加するだけで簡単に行えます。以下を作成してください。

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はtentacleを表示するものでした。

purple tentacleボタンが表示されるページにアクセスした後、ページ上にボタンが存在し、tentacle画像がまだ存在しないことを確認したいと考えます。

それは以下の検証によって行われます。

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'); です。これは、ボタンをクリックしてtentacleを表示したいことをテストフレームワークに伝えます。

ボタン上のクリックをシミュレートした後、以下を検証することにより、tentacleが表示されたかどうかを確認できます。

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

それほど悪くないでしょう? 開発マシンで http://localhost:3000/tests?target=purple-tentacle にアクセスして、自分でテストを試してみることができます。非常にすぐにpurple tentacleが表示され、すべてのテストが通過するはずです。

コマンドラインでプラグインのqunitテストを実行したい場合は、以下を実行できます。

bin/qunit --target purple-tentacle

(開発サーバーが起動していない場合は、--standaloneを追加してください)

(ここで purple-tentacle はプラグインのフォルダ名です)

テストのデバッグ

プラグインを記述するにつれ、テストがプラグイン内の問題を特定するのに役立ちます。テストを開発中、またはプラグインのコードに変更を加えた場合、テストが失敗する可能性があります。理由を理解するのに役立つように、Emberには pauseTest() と resumeTest() という便利なヘルパーがあります。

これらを使用するには、テストを一時停止したい箇所のテストコード内に await pauseTest() を追加します。ここで、ブラウザでテストを実行すると、pauseTest() を追加した箇所でテストが自動的に一時停止します。これにより、ページを検査したり、エラーを表示して問題のデバッグに役立てたりする機会が得られます。

ここから先へ

同じことの繰り返しのように聞こえるかもしれませんが、テストに関するEmberドキュメントは非常に優れています。また、javascriptテストディレクトリのテストを閲覧することで、Discourseが多様な機能をテストする方法を確認することもできるでしょう。そこから学べる例が多数あります。

テストを楽しんでください!


シリーズの続き

パート1: プラグインの基本
パート2: プラグインアウトレット
パート3: サイト設定
パート4: gitセットアップ
パート5: 管理者インターフェース
パート6: このトピック
パート7: プラグインの公開


このドキュメントはバージョン管理されています - github上のsuggestions changesで変更を提案してください。

「いいね!」 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