Skip to content

Michal/common_test/add-information-about-ct:comment-to-documentation #10271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: maint
Choose a base branch
from
Open

Michal/common_test/add-information-about-ct:comment-to-documentation #10271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions lib/common_test/doc/guides/ct_hooks_chapter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what about this different process organization depending on how you install a hook?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added table that presents this information


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 |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good to know how it behaves.

let's discuss on some occasion, if this should be documented and should it be done that way or other.
@IngelaAndin

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this text looks good as external doc but I do not think we should repeat it in two places. Decide on one an link it from the other place.

| -------------------------- | --------------------------------------------------------- | ------------------------------------------------------- |
| 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_

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is to detailed for external documentation, and could potential get forgotten when updating, I have not check, are all these functions documented callbacks? Perhaps this should be interna doc only. Maybe it would be possible
to write something like "all per_testcase functions will write comment to ..." etc

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes. I would prefer table to go to into internal docs as might be useful for us in future.

in external docs I would like a info note that for some callbacks ct:comment operation might not work (can it be easily explained why?). maybe list exact the callbacks.

then maybe have 2nd info note explaining that method of hook installation might further impact the above list (again, can it be easily explained why?). mayble list exact callbacks.

Providing some brief explanation, might be educative to users wanting to understand how stuff works.

[](){: #synchronizing }

## Synchronizing External User Applications with Common Test
Expand Down
14 changes: 14 additions & 0 deletions lib/common_test/src/ct.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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().
Expand Down
Loading