From 057db1fcc8e365084879f285fd332e1895eff3c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20W=C4=85sowski?= Date: Mon, 13 Oct 2025 19:16:37 +0200 Subject: [PATCH] Add information about ct:comment to documentation --- .../doc/guides/ct_hooks_chapter.md | 43 +++++++++++++++++++ lib/common_test/src/ct.erl | 14 ++++++ 2 files changed, 57 insertions(+) diff --git a/lib/common_test/doc/guides/ct_hooks_chapter.md b/lib/common_test/doc/guides/ct_hooks_chapter.md index f68b71d942d8..466107ece55a 100644 --- a/lib/common_test/doc/guides/ct_hooks_chapter.md +++ b/lib/common_test/doc/guides/ct_hooks_chapter.md @@ -281,6 +281,49 @@ After any post hook has been executed for all installed CTHs, skipped, respectively. You cannot affect the outcome of the tests any further at this point. +[](){: #comment } + +### Comment in hooks + +As mentioned in `ct:comment/1` same limitation regarding calling `ct:comment/1-2` +exists in hook functions. Calling `ct:comment/1-2` should only be done directly from +the process executing hook function, or it's descendant. + +Be aware that if you spawn a process in one hook function and keep it alive +while common_test has moved to calling another hook function, and you try to +execute `ct:comment/1-2` from this process the comment may not be printed in +correct place in html logs, or at all. + +Calling this function from process that is neither a common_test process, nor it's +descendant is no-op. + +This table presents information where `ct:comment/1-2` prints to, depending on how hook was installed: + +| Hook function | Install in: `ct_run`, `ct:run_test/1`, Test Specification | Install in: suite/0, init_per_suite/1, init_per_group/2 | +| -------------------------- | --------------------------------------------------------- | ------------------------------------------------------- | +| id/1 | init_per_suite row | init_per_suite row | +| init/2 | nowhere | init_per_suite row | +| post_all/3 | nowhere | nowhere | +| post_groups/4 | nowhere | nowhere | +| pre_init_per_suite/3 | init_per_suite row | init_per_suite row | +| post_init_per_suite/4 | init_per_suite row | init_per_suite row | +| pre_init_per_group/3,4 | init_per_group row | init_per_group row | +| post_init_per_group/4,5 | init_per_group row | init_per_group row | +| pre_init_per_testcase/3,4 | testcase row | testcase row | +| post_init_per_testcase/4,5 | testcase row | testcase row | +| post_init_per_testcase/4,5 | testcase row | testcase row | +| pre_end_per_testcase/3,4 | testcase row | testcase row | +| post_end_per_testcase/4,5 | testcase row | testcase row | +| pre_end_per_group/3,4 | end_per_group row | end_per_group row | +| post_end_per_group/4,5 | end_per_group row | end_per_group row | +| pre_end_per_suite/3 | end_per_suite row | end_per_suite row | +| post_end_per_suite/4 | end_per_suite row | end_per_suite row | +| on_tc_skip/4 | testcase row | testcase row | +| on_tc_fail/4 | nowhere | nowhere | +| terminate/1 | nowhere | end_per_suite row | + +_Table: Behavior of `ct:comment/1-2` depending on hook installation method_ + [](){: #synchronizing } ## Synchronizing External User Applications with Common Test diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl index 82dec1697db7..70ed6fc21bdf 100644 --- a/lib/common_test/src/ct.erl +++ b/lib/common_test/src/ct.erl @@ -1055,6 +1055,20 @@ suite result page. If called several times, only the last comment is printed. The test case return value `{comment,Comment}` overwrites the string set by this function. + +> #### Warning {: .warning } +> +> This function (and `ct:comment/2`) should only be called from the process running +> the common_test functions, typically the test case process or it's descendant. +> Be aware that if you spawn a new process in one common_test function (e.g. `init_per_suite`) +> and then execute `ct:comment/1-2` in that new process while the test execution has moved +> to another common_test function (e.g. `init_per_testcase` or test case function) the comment +> might not be printed in the correct place in html logs or at all. +> +> Calling this function from process that is neither a common_test process, nor it's +> descendant is no-op. +> +> Similar limitation exists for common_test hooks, see: [Comment in hooks](ct_hooks_chapter.md#comment) """. -spec comment(Comment) -> ok when Comment :: term().