From 326809388182ad23d22fffb437436d033b4939b1 Mon Sep 17 00:00:00 2001 From: Andrew Mayorov Date: Tue, 29 Aug 2023 21:16:26 +0400 Subject: [PATCH] feat(cth): add module-level documenation --- apps/emqx/test/emqx_cth_cluster.erl | 22 ++++++++++++++++ apps/emqx/test/emqx_cth_suite.erl | 41 +++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) diff --git a/apps/emqx/test/emqx_cth_cluster.erl b/apps/emqx/test/emqx_cth_cluster.erl index e24600181..3f8ea9a89 100644 --- a/apps/emqx/test/emqx_cth_cluster.erl +++ b/apps/emqx/test/emqx_cth_cluster.erl @@ -14,6 +14,28 @@ %% limitations under the License. %%-------------------------------------------------------------------- +%% @doc Common Test Helper / Running tests in a cluster +%% +%% This module allows setting up and tearing down clusters of EMQX nodes with +%% the purpose of running integration tests in a distributed environment, but +%% with the same isolation measures that `emqx_cth_suite` provides. +%% +%% Additionally to what `emqx_cth_suite` does with respect to isolation, each +%% node in the cluster is started with a separate, unique working directory. +%% +%% What should be started on each node is defined by the same appspecs that are +%% used by `emqx_cth_suite` to start applications on the CT node. However, there +%% are additional set of defaults applied to appspecs to make sure that the +%% cluster is started in a consistent, interconnected state, with no conflicts +%% between applications. +%% +%% Most of the time, you just need to: +%% 1. Describe the cluster with one or more _nodespecs_. +%% 2. Call `emqx_cth_cluster:start/2` before the testrun (e.g. in `init_per_suite/1` +%% or `init_per_group/2`), providing unique work dir (e.g. +%% `emqx_cth_suite:work_dir/1`). Save the result in a context. +%% 3. Call `emqx_cth_cluster:stop/1` after the testrun concludes (e.g. +%% in `end_per_suite/1` or `end_per_group/2`) with the result from step 2. -module(emqx_cth_cluster). -export([start/2]). diff --git a/apps/emqx/test/emqx_cth_suite.erl b/apps/emqx/test/emqx_cth_suite.erl index b70245e9d..090bca762 100644 --- a/apps/emqx/test/emqx_cth_suite.erl +++ b/apps/emqx/test/emqx_cth_suite.erl @@ -14,6 +14,47 @@ %% limitations under the License. %%-------------------------------------------------------------------- +%% @doc Common Test Helper / Running test suites +%% +%% The purpose of this module is to run application-level, integration +%% tests in an isolated fashion. +%% +%% Isolation is this context means that each testrun does not leave any +%% persistent state accessible to following testruns. The goal is to +%% make testruns completely independent of each other, of the order in +%% which they are executed, and of the testrun granularity, i.e. whether +%% they are executed individually or as part of a larger suite. This +%% should help to increase reproducibility and reduce the risk of false +%% positives. +%% +%% Isolation is achieved through the following measures: +%% * Each testrun completely terminates and unload all applications +%% started during the testrun. +%% * Each testrun is executed in a separate directory, usually under +%% common_test's private directory, where all persistent state should +%% be stored. +%% * Additionally, each cleans out few bits of persistent state that +%% survives the above measures, namely persistent VM terms related +%% to configuration and authentication (see `clean_suite_state/0`). +%% +%% Integration test in this context means a test that works with applications +%% as a whole, and needs to start and stop them as part of the test run. +%% For this, there's an abstraction called _appspec_ that describes how to +%% configure and start an application. +%% +%% The module also provides a set of default appspecs for some applications +%% that hide details and quirks of how to start them, to make it easier to +%% write test suites. +%% +%% Most of the time, you just need to: +%% 1. Describe the appspecs for the applications you want to test. +%% 2. Call `emqx_cth_sutie:start/2` to start the applications before the testrun +%% (e.g. in `init_per_suite/1` / `init_per_group/2`), providing the appspecs +%% and unique work dir for the testrun (e.g. `work_dir/1`). Save the result +%% in a context. +%% 3. Call `emqx_cth_sutie:stop/1` to stop the applications after the testrun +%% finishes (e.g. in `end_per_suite/1` / `end_per_group/2`), providing the +%% result from step 2. -module(emqx_cth_suite). -include_lib("common_test/include/ct.hrl").