diff options
Diffstat (limited to 'lib/common_test/doc/src')
41 files changed, 1792 insertions, 1172 deletions
diff --git a/lib/common_test/doc/src/Makefile b/lib/common_test/doc/src/Makefile index a0c89b1222..b5acdc6f95 100644 --- a/lib/common_test/doc/src/Makefile +++ b/lib/common_test/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2003-2012. All Rights Reserved. +# Copyright Ericsson AB 2003-2018. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -53,14 +53,14 @@ XML_REF3_FILES = ct.xml \ ct_slave.xml \ ct_property_test.xml \ ct_netconfc.xml \ - ct_hooks.xml + ct_hooks.xml \ + ct_testspec.xml XML_REF6_FILES = common_test_app.xml -XML_PART_FILES = part.xml -# part_notes.xml \ -# part_notes_history.xml +XML_PART_FILES = part.xml XML_CHAPTER_FILES = \ + introduction.xml \ basics_chapter.xml \ getting_started_chapter.xml \ install_chapter.xml \ @@ -75,8 +75,7 @@ XML_CHAPTER_FILES = \ event_handler_chapter.xml \ ct_hooks_chapter.xml \ dependencies_chapter.xml \ - notes.xml \ - notes_history.xml + notes.xml BOOK_FILES = book.xml @@ -105,11 +104,17 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf +SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml) + +TOP_SPECS_FILE = specs.xml + # ---------------------------------------------------- -# FLAGS +# FLAGS # ---------------------------------------------------- -XML_FLAGS += -DVIPS_FLAGS += +XML_FLAGS += +DVIPS_FLAGS += +SPECS_FLAGS = -I../../include -I../../../snmp/include \ + -I../../../kernel/include # ---------------------------------------------------- # Targets @@ -118,32 +123,34 @@ DVIPS_FLAGS += $(HTMLDIR)/%.gif: %.gif $(INSTALL_DATA) $< $@ -docs: pdf html man +docs: man pdf html $(TOP_PDF_FILE): $(XML_FILES) pdf: $(TOP_PDF_FILE) -html: gifs $(HTML_REF_MAN_FILE) +html: gifs $(HTML_REF_MAN_FILE) gifs: $(GIF_FILES:%=$(HTMLDIR)/%) man: $(MAN6_FILES) $(MAN3_FILES) $(MAN1_FILES) -debug opt: +debug opt: clean clean_docs: rm -rf $(HTMLDIR)/* + rm -rf $(XMLDIR) rm -f $(MAN1DIR)/* rm -f $(MAN3DIR)/* rm -f $(MAN6DIR)/* rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) - rm -f errs core *~ + rm -f $(SPECDIR)/* + rm -f errs core *~ # ---------------------------------------------------- # Release Target -# ---------------------------------------------------- +# ---------------------------------------------------- include $(ERL_TOP)/make/otp_release_targets.mk diff --git a/lib/common_test/doc/src/basics_chapter.xml b/lib/common_test/doc/src/basics_chapter.xml index 1a5a686fa0..95599ca1f1 100644 --- a/lib/common_test/doc/src/basics_chapter.xml +++ b/lib/common_test/doc/src/basics_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -75,7 +75,7 @@ <p><c>Common Test</c> is also a very useful tool for white-box testing Erlang code (for example, module testing), as the test programs can call exported Erlang - functions directly. there is very little overhead required for + functions directly. There is very little overhead required for implementing basic test suites and executing simple tests. For black-box testing Erlang software, Erlang RPC and standard O&M interfaces can be used for example. diff --git a/lib/common_test/doc/src/book.xml b/lib/common_test/doc/src/book.xml index 7fe5331aba..def139a0be 100644 --- a/lib/common_test/doc/src/book.xml +++ b/lib/common_test/doc/src/book.xml @@ -4,7 +4,7 @@ <book xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml index 10c93e2ed1..7887a2c3ea 100644 --- a/lib/common_test/doc/src/common_test_app.xml +++ b/lib/common_test/doc/src/common_test_app.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>PA1</rev> <file>common_test_app.sgml</file> </header> - <module>common_test</module> + <module since="">common_test</module> <modulesummary>A framework for automated testing of any target nodes.</modulesummary> <description> @@ -68,7 +68,7 @@ <funcs> <func> - <name>Module:all() -> Tests | {skip,Reason} </name> + <name since="">Module:all() -> Tests | {skip,Reason} </name> <fsummary>Returns the list of all test case groups and test cases in the module.</fsummary> <type> @@ -115,7 +115,7 @@ </func> <func> - <name>Module:groups() -> GroupDefs</name> + <name since="">Module:groups() -> GroupDefs</name> <fsummary>Returns a list of test case group definitions.</fsummary> <type> <v>GroupDefs = [Group]</v> @@ -140,7 +140,7 @@ </func> <func> - <name>Module:suite() -> [Info] </name> + <name since="">Module:suite() -> [Info] </name> <fsummary>Test suite info function (providing default data for the suite).</fsummary> <type> @@ -213,7 +213,7 @@ </func> <func> - <name>Module:init_per_suite(Config) -> NewConfig | {skip,Reason} | + <name since="">Module:init_per_suite(Config) -> NewConfig | {skip,Reason} | {skip_and_save,Reason,SaveConfig}</name> <fsummary>Test suite initializations.</fsummary> <type> @@ -224,7 +224,9 @@ </type> <desc> - <p>OPTIONAL</p> + <p>OPTIONAL; if this function is defined, then <seealso + marker="#Module:end_per_suite-1"><c>end_per_suite/1</c></seealso> + must also be defined.</p> <p>This configuration function is called as the first function in the suite. It typically contains initializations that are common for @@ -246,7 +248,7 @@ </func> <func> - <name>Module:end_per_suite(Config) -> term() | + <name since="">Module:end_per_suite(Config) -> term() | {save_config,SaveConfig}</name> <fsummary>Test suite finalization.</fsummary> <type> @@ -256,7 +258,9 @@ </type> <desc> - <p>OPTIONAL</p> + <p>OPTIONAL; if this function is defined, then <seealso + marker="#Module:init_per_suite-1"><c>init_per_suite/1</c></seealso> + must also be defined.</p> <p>This function is called as the last test case in the suite. It is meant to be used for cleaning up after @@ -268,7 +272,7 @@ </func> <func> - <name>Module:group(GroupName) -> [Info] </name> + <name since="OTP R15B">Module:group(GroupName) -> [Info] </name> <fsummary>Test case group information function (providing default data for a test case group, that is, its test cases and subgroups).</fsummary> @@ -348,7 +352,7 @@ </func> <func> - <name>Module:init_per_group(GroupName, Config) -> NewConfig | + <name since="">Module:init_per_group(GroupName, Config) -> NewConfig | {skip,Reason}</name> <fsummary>Test case group initializations.</fsummary> <type> @@ -360,7 +364,9 @@ </type> <desc> - <p>OPTIONAL</p> + <p>OPTIONAL; if this function is defined, then <seealso + marker="#Module:end_per_group-2"><c>end_per_group/2</c></seealso> + must also be defined.</p> <p>This configuration function is called before execution of a test case group. It typically contains initializations that are @@ -384,7 +390,7 @@ </func> <func> - <name>Module:end_per_group(GroupName, Config) -> term() | + <name since="">Module:end_per_group(GroupName, Config) -> term() | {return_group_result,Status}</name> <fsummary>Test case group finalization.</fsummary> <type> @@ -396,7 +402,9 @@ </type> <desc> - <p>OPTIONAL</p> + <p>OPTIONAL; if this function is defined, then <seealso + marker="#Module:init_per_group-2"><c>init_per_group/2</c></seealso> + must also be defined.</p> <p>This function is called after the execution of a test case group is finished. It is meant to be used for cleaning up after @@ -416,7 +424,7 @@ </func> <func> - <name>Module:init_per_testcase(TestCase, Config) -> NewConfig | {fail,Reason} | {skip,Reason}</name> + <name since="">Module:init_per_testcase(TestCase, Config) -> NewConfig | {fail,Reason} | {skip,Reason}</name> <fsummary>Test case initializations.</fsummary> <type> <v> TestCase = atom()</v> @@ -427,7 +435,10 @@ </type> <desc> - <p>OPTIONAL</p> + <p>OPTIONAL; if this function is defined, + then <seealso marker="#Module:end_per_testcase-2"> + <c>end_per_testcase/2</c></seealso> must also be + defined.</p> <p>This function is called before each test case. Argument <c>TestCase</c> is the test case name, and @@ -443,7 +454,7 @@ </func> <func> - <name>Module:end_per_testcase(TestCase, Config) -> term() | {fail,Reason} | {save_config,SaveConfig}</name> + <name since="">Module:end_per_testcase(TestCase, Config) -> term() | {fail,Reason} | {save_config,SaveConfig}</name> <fsummary>Test case finalization.</fsummary> <type> <v>TestCase = atom()</v> @@ -454,7 +465,10 @@ </type> <desc> - <p>OPTIONAL</p> + <p>OPTIONAL; if this function is defined, + then <seealso marker="#Module:init_per_testcase-2"> + <c>init_per_testcase/2</c></seealso> must also be + defined.</p> <p>This function is called after each test case, and can be used to clean up after @@ -472,7 +486,7 @@ </func> <func> - <name>Module:Testcase() -> [Info] </name> + <name since="OTP R14B">Module:Testcase() -> [Info] </name> <fsummary>Test case information function.</fsummary> <type> <v>Info = {timetrap,Time} | {require,Required} | {require,Name,Required} | {userdata,UserData} | {silent_connections,Conns}</v> @@ -546,7 +560,7 @@ </func> <func> - <name>Module:Testcase(Config) -> term() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit() </name> + <name since="OTP R14B">Module:Testcase(Config) -> term() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit() </name> <fsummary>A test case.</fsummary> <type> <v>Config = SaveConfig = [{Key,Value}]</v> @@ -566,7 +580,7 @@ (which also causes the test case process to terminate).</p> <p>Elements from the <c>Config</c> list can, for example, be read - with <c>proplists:get_value/2</c> in <c>STDLIB</c> + with <c>proplists:get_value/2</c> in STDLIB (or the macro <c>?config</c> defined in <c>ct.hrl</c>).</p> <p>If you decide not to run the test case after all, return diff --git a/lib/common_test/doc/src/config_file_chapter.xml b/lib/common_test/doc/src/config_file_chapter.xml index 62ebfccb98..db93744214 100644 --- a/lib/common_test/doc/src/config_file_chapter.xml +++ b/lib/common_test/doc/src/config_file_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2013</year> + <year>2004</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/cover_chapter.xml b/lib/common_test/doc/src/cover_chapter.xml index 094aa7d80c..6c180c276c 100644 --- a/lib/common_test/doc/src/cover_chapter.xml +++ b/lib/common_test/doc/src/cover_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2006</year><year>2014</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/ct.xml b/lib/common_test/doc/src/ct.xml index b6c862c233..83c0ecb309 100644 --- a/lib/common_test/doc/src/ct.xml +++ b/lib/common_test/doc/src/ct.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>ct.xml</file> </header> - <module>ct</module> + <module since="">ct</module> <modulesummary>Main user interface for the Common Test framework.</modulesummary> <description> @@ -70,24 +70,76 @@ <marker id="types"/> <taglist> - <tag><c>handle() = pid()</c></tag> - <item><marker id="type-handle"/> - <p>The identity (handle) of a connection.</p></item> - - <tag><c>target_name() = atom()</c></tag> - <item><marker id="type-target_name"/> - <p>A name and association to configuration data introduced - through a require statement, or a call to - <seealso marker="#require-2"><c>ct:require/2</c></seealso>, - for example, - <c>ct:require(mynodename,{node,[telnet]})</c>.</p></item> + <tag> + <marker id="type-handle"/> + <c>handle() = pid()</c> + </tag> + <item> + <p>The identity (handle) of a connection.</p> + </item> + + <tag> + <marker id="type-config_key"/> + <c>config_key() = atom()</c> + </tag> + <item> + <p>A configuration key which exists in a configuration file</p> + </item> + + <tag> + <marker id="type-target_name"/><c>target_name() = atom()</c> + </tag> + <item> + <p>A name and association to configuration data introduced + through a require statement, or a call to + <seealso marker="#require-2"><c>ct:require/2</c></seealso>, + for example, + <c>ct:require(mynodename,{node,[telnet]})</c>.</p> + </item> + + <tag> + <marker id="type-key_or_name"/> + <c>key_or_name() = config_key() | target_name()</c> + </tag> + <item/> + + <tag> + <marker id="type-conn_log_options"/> + <c>conn_log_options() = [conn_log_option()]</c> + </tag> + <item> + <p>Options that can be given to the <c>cth_conn_log</c> hook, + which is used for logging of NETCONF and Telnet + connections. See + <seealso marker="ct_netconfc#Logging">ct_netconfc</seealso> + or <seealso marker="ct_telnet#Logging">ct_telnet</seealso> + for description and examples of how to use this hook.</p> + </item> + + <tag> + <marker id="type-conn_log_option"/> + <c>conn_log_option() = {log_type,conn_log_type()} | {hosts,[key_or_name()]}</c> + </tag> + <item/> + + <tag> + <marker id="type-conn_log_type"/> + <c>conn_log_type() = raw | pretty | html | silent</c> + </tag> + <item/> + + <tag> + <marker id="type-conn_log_mod"/> + <c>conn_log_mod() = ct_netconfc | ct_telnet</c> + </tag> + <item/> </taglist> </section> <funcs> <func> - <name>abort_current_testcase(Reason) -> ok | {error, ErrorReason}</name> + <name since="">abort_current_testcase(Reason) -> ok | {error, ErrorReason}</name> <fsummary>Aborts the currently executing test case.</fsummary> <type> <v>Reason = term()</v> @@ -105,7 +157,7 @@ </func> <func> - <name>add_config(Callback, Config) -> ok | {error, Reason}</name> + <name since="OTP R14B">add_config(Callback, Config) -> ok | {error, Reason}</name> <fsummary>Loads configuration variables using the specified callback module and configuration string.</fsummary> <type> @@ -124,7 +176,7 @@ </func> <func> - <name>break(Comment) -> ok | {error, Reason}</name> + <name since="OTP R15B02">break(Comment) -> ok | {error, Reason}</name> <fsummary>Cancels any active timetrap and pause the execution of the current test case until the user calls function continue/0.</fsummary> <type> @@ -154,7 +206,7 @@ </func> <func> - <name>break(TestCase, Comment) -> ok | {error, Reason}</name> + <name since="OTP R15B02">break(TestCase, Comment) -> ok | {error, Reason}</name> <fsummary>Works the same way as break/1, only argument TestCase makes it possible to pause a test case executing in a parallel group.</fsummary> <type> @@ -176,7 +228,7 @@ </func> <func> - <name>capture_get() -> ListOfStrings</name> + <name since="OTP R15B">capture_get() -> ListOfStrings</name> <fsummary>Equivalent to capture_get([default]).</fsummary> <type> <v>ListOfStrings = [string()]</v> @@ -188,7 +240,7 @@ </func> <func> - <name>capture_get(ExclCategories) -> ListOfStrings</name> + <name since="OTP R15B">capture_get(ExclCategories) -> ListOfStrings</name> <fsummary>Returns and purges the list of text strings buffered during the latest session of capturing printouts to stdout.</fsummary> <type> @@ -210,7 +262,7 @@ </func> <func> - <name>capture_start() -> ok</name> + <name since="OTP R15B">capture_start() -> ok</name> <fsummary>Starts capturing all text strings printed to stdout during execution of the test case.</fsummary> <desc><marker id="capture_start-0"/> @@ -224,7 +276,7 @@ </func> <func> - <name>capture_stop() -> ok</name> + <name since="OTP R15B">capture_stop() -> ok</name> <fsummary>Stops capturing text strings (a session started with capture_start/0).</fsummary> <desc><marker id="capture_stop-0"/> @@ -238,7 +290,7 @@ </func> <func> - <name>comment(Comment) -> ok</name> + <name since="">comment(Comment) -> ok</name> <fsummary>Prints the specified Comment in the comment field in the table on the test suite result page.</fsummary> <type> @@ -255,7 +307,7 @@ </func> <func> - <name>comment(Format, Args) -> ok</name> + <name since="OTP R15B">comment(Format, Args) -> ok</name> <fsummary>Prints the formatted string in the comment field in the table on the test suite result page.</fsummary> <type> @@ -274,7 +326,7 @@ </func> <func> - <name>continue() -> ok</name> + <name since="OTP R15B02">continue() -> ok</name> <fsummary>This function must be called to continue after a test case (not executing in a parallel group) has called break/1.</fsummary> <desc><marker id="continue-0"/> @@ -285,7 +337,7 @@ </func> <func> - <name>continue(TestCase) -> ok</name> + <name since="OTP R15B02">continue(TestCase) -> ok</name> <fsummary>This function must be called to continue after a test case has called break/2.</fsummary> <type> @@ -301,7 +353,7 @@ </func> <func> - <name>decrypt_config_file(EncryptFileName, TargetFileName) -> ok | {error, Reason}</name> + <name since="">decrypt_config_file(EncryptFileName, TargetFileName) -> ok | {error, Reason}</name> <fsummary>Decrypts EncryptFileName, previously generated with encrypt_config_file/2,3.</fsummary> <type> @@ -320,7 +372,7 @@ </func> <func> - <name>decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> ok | {error, Reason}</name> + <name since="">decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> ok | {error, Reason}</name> <fsummary>Decrypts EncryptFileName, previously generated with encrypt_config_file/2,3.</fsummary> <type> @@ -338,7 +390,7 @@ </func> <func> - <name>encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error, Reason}</name> + <name since="">encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error, Reason}</name> <fsummary>Encrypts the source configuration file with DES3 and saves the result in file EncryptFileName.</fsummary> <type> @@ -364,7 +416,7 @@ </func> <func> - <name>encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -> ok | {error, Reason}</name> + <name since="">encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -> ok | {error, Reason}</name> <fsummary>Encrypts the source configuration file with DES3 and saves the result in the target file EncryptFileName.</fsummary> <type> @@ -390,7 +442,7 @@ </func> <func> - <name>fail(Reason) -> ok</name> + <name since="">fail(Reason) -> ok</name> <fsummary>Terminates a test case with the specified error Reason.</fsummary> <type> @@ -402,7 +454,7 @@ </func> <func> - <name>fail(Format, Args) -> ok</name> + <name since="OTP R15B">fail(Format, Args) -> ok</name> <fsummary>Terminates a test case with an error message specified by a format string and a list of values (used as arguments to io_lib:format/2).</fsummary> @@ -418,7 +470,7 @@ </func> <func> - <name>get_config(Required) -> Value</name> + <name since="">get_config(Required) -> Value</name> <fsummary>Equivalent to get_config(Required, undefined, []).</fsummary> <desc><marker id="get_config-1"/> <p>Equivalent to <seealso marker="#get_config-3"><c>ct:get_config(Required, @@ -427,7 +479,7 @@ </func> <func> - <name>get_config(Required, Default) -> Value</name> + <name since="">get_config(Required, Default) -> Value</name> <fsummary>Equivalent to get_config(Required, Default, []).</fsummary> <desc><marker id="get_config-2"/> <p>Equivalent to <seealso marker="#get_config-3"><c>ct:get_config(Required, @@ -436,7 +488,7 @@ </func> <func> - <name>get_config(Required, Default, Opts) -> ValueOrElement</name> + <name since="">get_config(Required, Default, Opts) -> ValueOrElement</name> <fsummary>Reads configuration data values.</fsummary> <type> <v>Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}</v> @@ -502,7 +554,7 @@ </func> <func> - <name>get_event_mgr_ref() -> EvMgrRef</name> + <name since="OTP 17.5">get_event_mgr_ref() -> EvMgrRef</name> <fsummary>Gets a reference to the <c>Common Test</c> event manager.</fsummary> <type> <v>EvMgrRef = atom()</v> @@ -520,7 +572,17 @@ </func> <func> - <name>get_status() -> TestStatus | {error, Reason} | no_tests_running</name> + <name since="OTP 21.0">get_progname() -> string()</name> + <fsummary>Returns the command used to start this Erlang instance.</fsummary> + <desc><marker id="get_progname-0"/> + <p>Returns the command used to start this Erlang instance. + If this information could not be found, the string + <c>"no_prog_name"</c> is returned.</p> + </desc> + </func> + + <func> + <name since="">get_status() -> TestStatus | {error, Reason} | no_tests_running</name> <fsummary>Returns status of ongoing test.</fsummary> <type> <v>TestStatus = [StatusElem]</v> @@ -546,7 +608,7 @@ </func> <func> - <name>get_target_name(Handle) -> {ok, TargetName} | {error, Reason}</name> + <name since="">get_target_name(Handle) -> {ok, TargetName} | {error, Reason}</name> <fsummary>Returns the name of the target that the specified connection belongs to.</fsummary> <type> @@ -560,7 +622,7 @@ </func> <func> - <name>get_testspec_terms() -> TestSpecTerms | undefined</name> + <name since="OTP 18.0">get_testspec_terms() -> TestSpecTerms | undefined</name> <fsummary>Gets a list of all test specification terms used to configure and run this test.</fsummary> <type> @@ -574,7 +636,7 @@ </func> <func> - <name>get_testspec_terms(Tags) -> TestSpecTerms | undefined</name> + <name since="OTP 18.0">get_testspec_terms(Tags) -> TestSpecTerms | undefined</name> <fsummary>Reads one or more terms from the test specification used to configure and run this test.</fsummary> <type> @@ -601,7 +663,7 @@ </func> <func> - <name>get_timetrap_info() -> {Time, {Scaling,ScaleVal}}</name> + <name since="OTP R15B">get_timetrap_info() -> {Time, {Scaling,ScaleVal}}</name> <fsummary>Reads information about the timetrap set for the current test case.</fsummary> <type> @@ -620,7 +682,22 @@ </func> <func> - <name>install(Opts) -> ok | {error, Reason}</name> + <name since="OTP 19.1">get_verbosity(Category) -> Level | undefined</name> + <fsummary>Read the verbosity level for a logging category.</fsummary> + <type> + <v>Category = default | atom()</v> + <v>Level = integer()</v> + </type> + <desc><marker id="get_verbosity-1"/> + <p>This function returns the verbosity level for the specified logging + category. See the <seealso marker="write_test_chapter#logging"> + User's Guide</seealso> for details. Use the value <c>default</c> to read + the general verbosity level.</p> + </desc> + </func> + + <func> + <name since="">install(Opts) -> ok | {error, Reason}</name> <fsummary>Installs configuration files and event handlers.</fsummary> <type> <v>Opts = [Opt]</v> @@ -647,7 +724,7 @@ </func> <func> - <name>listenv(Telnet) -> [Env]</name> + <name since="">listenv(Telnet) -> [Env]</name> <fsummary>Performs command listenv on the specified Telnet connection and returns the result as a list of key-value pairs.</fsummary> <type> @@ -663,7 +740,7 @@ </func> <func> - <name>log(Format) -> ok</name> + <name since="">log(Format) -> ok</name> <fsummary>Equivalent to log(default, 50, Format, [], []).</fsummary> <desc><marker id="log-1"/> <p>Equivalent to @@ -672,7 +749,7 @@ </func> <func> - <name>log(X1, X2) -> ok</name> + <name since="">log(X1, X2) -> ok</name> <fsummary>Equivalent to log(Category, Importance, Format, FormatArgs, []).</fsummary> <type> @@ -686,7 +763,7 @@ </func> <func> - <name>log(X1, X2, X3) -> ok</name> + <name since="">log(X1, X2, X3) -> ok</name> <fsummary>Equivalent to log(Category, Importance, Format, FormatArgs, Opts).</fsummary> <type> @@ -701,7 +778,7 @@ </func> <func> - <name>log(X1, X2, X3, X4) -> ok</name> + <name since="OTP R15B02">log(X1, X2, X3, X4) -> ok</name> <fsummary>Equivalent to log(Category, Importance, Format, FormatArgs, Opts).</fsummary> <type> @@ -717,7 +794,7 @@ </func> <func> - <name>log(Category, Importance, Format, FormatArgs, Opts) -> ok</name> + <name since="OTP 18.3">log(Category, Importance, Format, FormatArgs, Opts) -> ok</name> <fsummary>Prints from a test case to the log file.</fsummary> <type> <v>Category = atom()</v> @@ -725,7 +802,7 @@ <v>Format = string()</v> <v>FormatArgs = list()</v> <v>Opts = [Opt]</v> - <v>Opt = no_css | esc_chars</v> + <v>Opt = {heading,string()} | no_css | esc_chars</v> </type> <desc><marker id="log-5"/> <p>Prints from a test case to the log file.</p> @@ -748,7 +825,7 @@ </func> <func> - <name>make_priv_dir() -> ok | {error, Reason}</name> + <name since="OTP R15B01">make_priv_dir() -> ok | {error, Reason}</name> <fsummary>If the test has been started with option create_priv_dir set to manual_per_tc, in order for the test case to use the private directory, it must first create it by calling this function.</fsummary> @@ -764,7 +841,7 @@ </func> <func> - <name>notify(Name, Data) -> ok</name> + <name since="OTP R15B02">notify(Name, Data) -> ok</name> <fsummary>Sends an asynchronous notification of type Name with Data to the <c>Common Test</c> event manager.</fsummary> <type> @@ -777,59 +854,77 @@ caught by any installed event manager.</p> <p>See also - <seealso marker="stdlib:gen_event"><c>stdlib:gen_event(3)</c></seealso>.</p> + <seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso>.</p> </desc> </func> <func> - <name>pal(Format) -> ok</name> - <fsummary>Equivalent to pal(default, 50, Format, []).</fsummary> + <name since="">pal(Format) -> ok</name> + <fsummary>Equivalent to pal(default, 50, Format, [], []).</fsummary> <desc><marker id="pal-1"/> <p>Equivalent to - <seealso marker="#pal-4"><c>ct:pal(default, 50, Format, - [])</c></seealso>.</p> + <seealso marker="#pal-5"><c>ct:pal(default, 50, Format, + [], [])</c></seealso>.</p> </desc> </func> <func> - <name>pal(X1, X2) -> ok</name> + <name since="">pal(X1, X2) -> ok</name> <fsummary>Equivalent to pal(Category, Importance, Format, - FormatArgs).</fsummary> + FormatArgs, []).</fsummary> <type> <v>X1 = Category | Importance | Format</v> <v>X2 = Format | FormatArgs</v> </type> <desc><marker id="pal-2"/> - <p>Equivalent to <seealso marker="#pal-4"><c>ct:pal(Category, - Importance, Format, FormatArgs)</c></seealso>.</p> + <p>Equivalent to <seealso marker="#pal-5"><c>ct:pal(Category, + Importance, Format, FormatArgs, [])</c></seealso>.</p> </desc> </func> <func> - <name>pal(X1, X2, X3) -> ok</name> + <name since="">pal(X1, X2, X3) -> ok</name> <fsummary>Equivalent to pal(Category, Importance, Format, - FormatArgs).</fsummary> + FormatArgs, Opts).</fsummary> <type> <v>X1 = Category | Importance</v> <v>X2 = Importance | Format</v> - <v>X3 = Format | FormatArgs</v> + <v>X3 = Format | FormatArgs | Opts</v> </type> <desc><marker id="pal-3"/> - <p>Equivalent to <seealso marker="#pal-4"><c>ct:pal(Category, - Importance, Format, FormatArgs)</c></seealso>.</p> + <p>Equivalent to <seealso marker="#pal-5"><c>ct:pal(Category, + Importance, Format, FormatArgs, Opts)</c></seealso>.</p> </desc> </func> <func> - <name>pal(Category, Importance, Format, FormatArgs) -> ok</name> + <name since="OTP R15B02">pal(X1, X2, X3, X4) -> ok</name> + <fsummary>Equivalent to pal(Category, Importance, Format, + FormatArgs, Opts).</fsummary> + <type> + <v>X1 = Category | Importance</v> + <v>X2 = Importance | Format</v> + <v>X3 = Format | FormatArgs</v> + <v>X4 = FormatArgs | Opts</v> + </type> + <desc><marker id="pal-4"/> + <p>Equivalent to <seealso marker="#pal-5"><c>ct:pal(Category, + Importance, Format, FormatArgs, Opts)</c></seealso>.</p> + </desc> + </func> + + <func> + <name since="OTP 19.2">pal(Category, Importance, Format, FormatArgs, Opts) -> ok</name> <fsummary>Prints and logs from a test case.</fsummary> <type> <v>Category = atom()</v> <v>Importance = integer()</v> <v>Format = string()</v> <v>FormatArgs = list()</v> + <v>Opts = [Opt]</v> + <v>Opt = {heading,string()} | no_css</v> </type> - <desc><marker id="pal-4"/> + <desc><marker id="pal-5"/> <p>Prints and logs from a test case.</p> <p>This function is meant for printing a string from a test case, @@ -850,7 +945,7 @@ </func> <func> - <name>parse_table(Data) -> {Heading, Table}</name> + <name since="">parse_table(Data) -> {Heading, Table}</name> <fsummary>Parses the printout from an SQL table and returns a list of tuples.</fsummary> <type> @@ -872,53 +967,71 @@ </func> <func> - <name>print(Format) -> ok</name> - <fsummary>Equivalent to print(default, 50, Format, []).</fsummary> + <name since="">print(Format) -> ok</name> + <fsummary>Equivalent to print(default, 50, Format, [], []).</fsummary> <desc><marker id="print-1"/> - <p>Equivalent to <seealso marker="#print-4"><c>ct:print(default, - 50, Format, [])</c></seealso>.</p> + <p>Equivalent to <seealso marker="#print-5"><c>ct:print(default, + 50, Format, [], [])</c></seealso>.</p> </desc> </func> <func> - <name>print(X1, X2) -> ok</name> + <name since="OTP R15B02">print(X1, X2) -> ok</name> <fsummary>Equivalent to print(Category, Importance, Format, - FormatArgs).</fsummary> + FormatArgs, []).</fsummary> <type> <v>X1 = Category | Importance | Format</v> <v>X2 = Format | FormatArgs</v> </type> <desc><marker id="print-2"/> - <p>Equivalent to <seealso marker="#print-4"><c>ct:print(Category, - Importance, Format, FormatArgs)</c></seealso>.</p> + <p>Equivalent to <seealso marker="#print-5"><c>ct:print(Category, + Importance, Format, FormatArgs, [])</c></seealso>.</p> </desc> </func> <func> - <name>print(X1, X2, X3) -> ok</name> + <name since="">print(X1, X2, X3) -> ok</name> <fsummary>Equivalent to print(Category, Importance, Format, - FormatArgs).</fsummary> + FormatArgs, Opts).</fsummary> <type> <v>X1 = Category | Importance</v> <v>X2 = Importance | Format</v> - <v>X3 = Format | FormatArgs</v> + <v>X3 = Format | FormatArgs | Opts</v> </type> <desc><marker id="print-3"/> - <p>Equivalent to <seealso marker="#print-4"><c>ct:print(Category, - Importance, Format, FormatArgs)</c></seealso>.</p> + <p>Equivalent to <seealso marker="#print-5"><c>ct:print(Category, + Importance, Format, FormatArgs, Opts)</c></seealso>.</p> </desc> </func> <func> - <name>print(Category, Importance, Format, FormatArgs) -> ok</name> + <name since="OTP R15B02">print(X1, X2, X3, X4) -> ok</name> + <fsummary>Equivalent to print(Category, Importance, Format, + FormatArgs, Opts).</fsummary> + <type> + <v>X1 = Category | Importance</v> + <v>X2 = Importance | Format</v> + <v>X3 = Format | FormatArgs</v> + <v>X4 = FormatArgs | Opts</v> + </type> + <desc><marker id="print-4"/> + <p>Equivalent to <seealso marker="#print-5"><c>ct:print(Category, + Importance, Format, FormatArgs, Opts)</c></seealso>.</p> + </desc> + </func> + + <func> + <name since="OTP 19.2">print(Category, Importance, Format, FormatArgs, Opts) -> ok</name> <fsummary>Prints from a test case to the console.</fsummary> <type> <v>Category = atom()</v> <v>Importance = integer()</v> <v>Format = string()</v> <v>FormatArgs = list()</v> + <v>Opts = [Opt]</v> + <v>Opt = {heading,string()}</v> </type> - <desc><marker id="print-4"/> + <desc><marker id="print-5"/> <p>Prints from a test case to the console.</p> <p>This function is meant for printing a string from a test case to @@ -935,7 +1048,7 @@ </func> <func> - <name>reload_config(Required) -> ValueOrElement</name> + <name since="OTP R14B">reload_config(Required) -> ValueOrElement | {error, Reason}</name> <fsummary>Reloads configuration file containing specified configuration key.</fsummary> <type> @@ -957,8 +1070,44 @@ </desc> </func> + <func> + <name since="OTP 20.2">remaining_test_procs() -> {TestProcs,SharedGL,OtherGLs}</name> + <fsummary>>This function will return the identity of test- and group + leader processes that are still running at the time of this call.</fsummary> + <type> + <v>TestProcs = [{pid(),GL}]</v> + <v>GL = pid()</v> + <v>SharedGL = pid()</v> + <v>OtherGLs = [pid()]</v> + </type> + <desc><marker id="remaining_test_procs-0"/> + <p>This function will return the identity of test- and group + leader processes that are still running at the time of this call. + <c>TestProcs</c> are processes in the system that have a Common Test IO + process as group leader. <c>SharedGL</c> is the central Common Test + IO process, responsible for printing to log files for configuration + functions and sequentially executing test cases. <c>OtherGLs</c> are + Common Test IO processes that print to log files for test cases + in parallel test case groups.</p> + <p>The process information returned by this function may be + used to locate and terminate remaining processes after tests have + finished executing. The function would typically by called from + Common Test Hook functions.</p> + <p>Note that processes that execute configuration functions or + test cases are never included in <c>TestProcs</c>. It is therefore safe + to use post configuration hook functions (such as post_end_per_suite, + post_end_per_group, post_end_per_testcase) to terminate all processes + in <c>TestProcs</c> that have the current group leader process as its group + leader.</p> + <p>Note also that the shared group leader (<c>SharedGL</c>) must never be + terminated by the user, only by Common Test. Group leader processes + for parallel test case groups (<c>OtherGLs</c>) may however be terminated + in post_end_per_group hook functions.</p> + </desc> + </func> + <func> - <name>remove_config(Callback, Config) -> ok</name> + <name since="OTP R14B">remove_config(Callback, Config) -> ok</name> <fsummary>Removes configuration variables (together with their aliases) that were loaded with specified callback module and configuration string.</fsummary> @@ -975,7 +1124,7 @@ </func> <func> - <name>require(Required) -> ok | {error, Reason}</name> + <name since="">require(Required) -> ok | {error, Reason}</name> <fsummary>Checks if the required configuration is available.</fsummary> <type> <v>Required = Key | {Key, SubKeys} | {Key, SubKey, SubKeys}</v> @@ -1029,7 +1178,7 @@ </func> <func> - <name>require(Name, Required) -> ok | {error, Reason}</name> + <name since="">require(Name, Required) -> ok | {error, Reason}</name> <fsummary>Checks if the required configuration is available and gives it a name.</fsummary> <type> @@ -1088,7 +1237,7 @@ </func> <func> - <name>run(TestDirs) -> Result</name> + <name since="">run(TestDirs) -> Result</name> <fsummary>Runs all test cases in all suites in the specified directories.</fsummary> <type> @@ -1102,7 +1251,7 @@ </func> <func> - <name>run(TestDir, Suite) -> Result</name> + <name since="">run(TestDir, Suite) -> Result</name> <fsummary>Runs all test cases in the specified suite.</fsummary> <desc><marker id="run-2"/> <p>Runs all test cases in the specified suite.</p> @@ -1112,7 +1261,7 @@ </func> <func> - <name>run(TestDir, Suite, Cases) -> Result</name> + <name since="">run(TestDir, Suite, Cases) -> Result</name> <fsummary>Runs the specified test cases.</fsummary> <type> <v>TestDir = string()</v> @@ -1134,12 +1283,12 @@ </func> <func> - <name>run_test(Opts) -> Result</name> + <name since="">run_test(Opts) -> Result</name> <fsummary>Runs tests as specified by the combination of options in Opts.</fsummary> <type> <v>Opts = [OptTuples]</v> - <v>OptTuples = {dir, TestDirs} | {suite, Suites} | {group, Groups} | {testcase, Cases} | {spec, TestSpecs} | {join_specs, Bool} | {label, Label} | {config, CfgFiles} | {userconfig, UserConfig} | {allow_user_terms, Bool} | {logdir, LogDir} | {silent_connections, Conns} | {stylesheet, CSSFile} | {cover, CoverSpecFile} | {cover_stop, Bool} | {step, StepOpts} | {event_handler, EventHandlers} | {include, InclDirs} | {auto_compile, Bool} | {abort_if_missing_suites, Bool} | {create_priv_dir, CreatePrivDir} | {multiply_timetraps, M} | {scale_timetraps, Bool} | {repeat, N} | {duration, DurTime} | {until, StopTime} | {force_stop, ForceStop} | {decrypt, DecryptKeyOrFile} | {refresh_logs, LogDir} | {logopts, LogOpts} | {verbosity, VLevels} | {basic_html, Bool} | {esc_chars, Bool} | {ct_hooks, CTHs} | {enable_builtin_hooks, Bool} | {release_shell, Bool}</v> + <v>OptTuples = {dir, TestDirs} | {suite, Suites} | {group, Groups} | {testcase, Cases} | {spec, TestSpecs} | {join_specs, Bool} | {label, Label} | {config, CfgFiles} | {userconfig, UserConfig} | {allow_user_terms, Bool} | {logdir, LogDir} | {silent_connections, Conns} | {stylesheet, CSSFile} | {cover, CoverSpecFile} | {cover_stop, Bool} | {step, StepOpts} | {event_handler, EventHandlers} | {include, InclDirs} | {auto_compile, Bool} | {abort_if_missing_suites, Bool} | {create_priv_dir, CreatePrivDir} | {multiply_timetraps, M} | {scale_timetraps, Bool} | {repeat, N} | {duration, DurTime} | {until, StopTime} | {force_stop, ForceStop} | {decrypt, DecryptKeyOrFile} | {refresh_logs, LogDir} | {logopts, LogOpts} | {verbosity, VLevels} | {basic_html, Bool} | {esc_chars, Bool} | {keep_logs,KeepSpec} | {ct_hooks, CTHs} | {enable_builtin_hooks, Bool} | {release_shell, Bool}</v> <v>TestDirs = [string()] | string()</v> <v>Suites = [string()] | [atom()] | string() | atom()</v> <v>Cases = [atom()] | atom()</v> @@ -1175,6 +1324,7 @@ <v>VLevels = VLevel | [{Category, VLevel}]</v> <v>VLevel = integer()</v> <v>Category = atom()</v> + <v>KeepSpec = all | pos_integer()</v> <v>CTHs = [CTHModule | {CTHModule, CTHInitArgs}]</v> <v>CTHModule = atom()</v> <v>CTHInitArgs = term()</v> @@ -1205,7 +1355,7 @@ </func> <func> - <name>run_testspec(TestSpec) -> Result</name> + <name since="">run_testspec(TestSpec) -> Result</name> <fsummary>Runs a test specified by TestSpec.</fsummary> <type> <v>TestSpec = [term()]</v> @@ -1225,7 +1375,22 @@ </func> <func> - <name>sleep(Time) -> ok</name> + <name since="OTP 19.1">set_verbosity(Category, Level) -> ok</name> + <fsummary>Set the verbosity level for a logging category.</fsummary> + <type> + <v>Category = default | atom()</v> + <v>Level = integer()</v> + </type> + <desc><marker id="set_verbosity-2"/> + <p>Use this function to set, or modify, the verbosity level for a logging + category. See the <seealso marker="write_test_chapter#logging"> + User's Guide</seealso> for details. Use the value <c>default</c> to set the + general verbosity level.</p> + </desc> + </func> + + <func> + <name since="OTP R14B">sleep(Time) -> ok</name> <fsummary>This function, similar to timer:sleep/1, suspends the test case for a specified time.</fsummary> <type> @@ -1236,7 +1401,7 @@ <v>Millisecs = integer() | float()</v> </type> <desc><marker id="sleep-1"/> - <p>This function, similar to <c>timer:sleep/1</c> in <c>STDLIB</c>, + <p>This function, similar to <c>timer:sleep/1</c> in STDLIB, suspends the test case for a specified time. However, this function also multiplies <c>Time</c> with the <c>multiply_timetraps</c> value (if set) and under certain @@ -1247,7 +1412,7 @@ </func> <func> - <name>start_interactive() -> ok</name> + <name since="">start_interactive() -> ok</name> <fsummary>Starts <c>Common Test</c> in interactive mode.</fsummary> <desc><marker id="start_interactive-0"/> <p>Starts <c>Common Test</c> in interactive mode.</p> @@ -1275,7 +1440,7 @@ </func> <func> - <name>step(TestDir, Suite, Case) -> Result</name> + <name since="">step(TestDir, Suite, Case) -> Result</name> <fsummary>Steps through a test case with the debugger.</fsummary> <type> <v>Case = atom()</v> @@ -1288,7 +1453,7 @@ </func> <func> - <name>step(TestDir, Suite, Case, Opts) -> Result</name> + <name since="">step(TestDir, Suite, Case, Opts) -> Result</name> <fsummary>Steps through a test case with the debugger.</fsummary> <type> <v>Case = atom()</v> @@ -1305,7 +1470,7 @@ </func> <func> - <name>stop_interactive() -> ok</name> + <name since="">stop_interactive() -> ok</name> <fsummary>Exits the interactive mode.</fsummary> <desc><marker id="stop_interactive-0"/> <p>Exits the interactive mode.</p> @@ -1317,7 +1482,7 @@ </func> <func> - <name>sync_notify(Name, Data) -> ok</name> + <name since="OTP R15B02">sync_notify(Name, Data) -> ok</name> <fsummary>Sends a synchronous notification of type Name with Data to the <c>Common Test</c> event manager.</fsummary> <type> @@ -1330,13 +1495,13 @@ caught by any installed event manager.</p> <p>See also - <seealso marker="stdlib:gen_event"><c>stdlib:gen_event(3)</c></seealso>. + <seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso>. </p> </desc> </func> <func> - <name>testcases(TestDir, Suite) -> Testcases | {error, Reason}</name> + <name since="">testcases(TestDir, Suite) -> Testcases | {error, Reason}</name> <fsummary>Returns all test cases in the specified suite.</fsummary> <type> <v>TestDir = string()</v> @@ -1350,14 +1515,14 @@ </func> <func> - <name>timetrap(Time) -> ok</name> + <name since="OTP R14B">timetrap(Time) -> ok</name> <fsummary>Sets a new timetrap for the running test case.</fsummary> <type> <v>Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity | Func</v> <v>Hours = integer()</v> <v>Mins = integer()</v> <v>Secs = integer()</v> - <v>Millisecs = integer() | float()</v> + <v>Millisecs = integer()</v> <v>Func = {M, F, A} | function()</v> <v>M = atom()</v> <v>F = atom()</v> @@ -1374,7 +1539,7 @@ </func> <func> - <name>userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}</name> + <name since="">userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}</name> <fsummary>Returns any data specified with tag userdata in the list of tuples returned from Suite:suite/0.</fsummary> <type> @@ -1391,7 +1556,7 @@ </func> <func> - <name>userdata(TestDir, Suite, Case::GroupOrCase) -> TCUserData | {error, Reason}</name> + <name since="">userdata(TestDir, Suite, Case::GroupOrCase) -> TCUserData | {error, Reason}</name> <fsummary>Returns any data specified with tag userdata in the list of tuples returned from Suite:group(GroupName) or Suite:Case().</fsummary> <type> diff --git a/lib/common_test/doc/src/ct_cover.xml b/lib/common_test/doc/src/ct_cover.xml index be09c08a68..61365d3522 100644 --- a/lib/common_test/doc/src/ct_cover.xml +++ b/lib/common_test/doc/src/ct_cover.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>ct_cover.xml</file> </header> - <module>ct_cover</module> + <module since="">ct_cover</module> <modulesummary>Common Test framework code coverage support module. </modulesummary> @@ -47,7 +47,7 @@ <funcs> <func> - <name>add_nodes(Nodes) -> {ok, StartedNodes} | {error, Reason}</name> + <name since="">add_nodes(Nodes) -> {ok, StartedNodes} | {error, Reason}</name> <fsummary>Adds nodes to current cover test (only works if cover support is active).</fsummary> <type> @@ -67,7 +67,7 @@ </func> <func> - <name>cross_cover_analyse(Level, Tests) -> ok</name> + <name since="OTP R16B">cross_cover_analyse(Level, Tests) -> ok</name> <fsummary>Accumulates cover results over multiple tests.</fsummary> <type> <v>Level = overview | details</v> @@ -83,7 +83,7 @@ </func> <func> - <name>remove_nodes(Nodes) -> ok | {error, Reason}</name> + <name since="">remove_nodes(Nodes) -> ok | {error, Reason}</name> <fsummary>Removes nodes from the current cover test.</fsummary> <type> <v>Nodes = [atom()]</v> diff --git a/lib/common_test/doc/src/ct_ftp.xml b/lib/common_test/doc/src/ct_ftp.xml index 0598dcbe3e..7ee6049486 100644 --- a/lib/common_test/doc/src/ct_ftp.xml +++ b/lib/common_test/doc/src/ct_ftp.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,14 +32,12 @@ <rev>A</rev> <file>ct_ftp.xml</file> </header> - <module>ct_ftp</module> - <modulesummary>FTP client module (based on the FTP support of the Inets - application).</modulesummary> + <module since="">ct_ftp</module> + <modulesummary>FTP client module (based on the FTP application).</modulesummary> <description> - <p>FTP client module (based on the FTP support of the <c>Inets</c> - application).</p> + <p>FTP client module (based on the <c>ftp</c> application).</p> </description> @@ -61,7 +59,7 @@ <funcs> <func> - <name>cd(Connection, Dir) -> ok | {error, Reason}</name> + <name since="">cd(Connection, Dir) -> ok | {error, Reason}</name> <fsummary>Changes directory on remote host.</fsummary> <type> <v>Connection = connection()</v> @@ -73,7 +71,7 @@ </func> <func> - <name>close(Connection) -> ok | {error, Reason}</name> + <name since="">close(Connection) -> ok | {error, Reason}</name> <fsummary>Closes the FTP connection.</fsummary> <type> <v>Connection = connection()</v> @@ -84,7 +82,7 @@ </func> <func> - <name>delete(Connection, File) -> ok | {error, Reason}</name> + <name since="">delete(Connection, File) -> ok | {error, Reason}</name> <fsummary>Deletes a file on remote host.</fsummary> <type> <v>Connection = connection()</v> @@ -96,7 +94,7 @@ </func> <func> - <name>get(KeyOrName, RemoteFile, LocalFile) -> ok | {error, Reason}</name> + <name since="">get(KeyOrName, RemoteFile, LocalFile) -> ok | {error, Reason}</name> <fsummary>Opens an FTP connection and fetches a file from the remote host.</fsummary> <type> @@ -124,7 +122,7 @@ </func> <func> - <name>ls(Connection, Dir) -> {ok, Listing} | {error, Reason}</name> + <name since="">ls(Connection, Dir) -> {ok, Listing} | {error, Reason}</name> <fsummary>Lists directory Dir.</fsummary> <type> <v>Connection = connection()</v> @@ -137,7 +135,7 @@ </func> <func> - <name>open(KeyOrName) -> {ok, Handle} | {error, Reason}</name> + <name since="">open(KeyOrName) -> {ok, Handle} | {error, Reason}</name> <fsummary>Opens an FTP connection to the specified node.</fsummary> <type> <v>KeyOrName = Key | Name</v> @@ -166,7 +164,7 @@ </func> <func> - <name>put(KeyOrName, LocalFile, RemoteFile) -> ok | {error, Reason}</name> + <name since="">put(KeyOrName, LocalFile, RemoteFile) -> ok | {error, Reason}</name> <fsummary>Opens an FTP connection and sends a file to the remote host.</fsummary> <type> @@ -205,7 +203,7 @@ </func> <func> - <name>recv(Connection, RemoteFile) -> ok | {error, Reason}</name> + <name since="">recv(Connection, RemoteFile) -> ok | {error, Reason}</name> <fsummary>Fetches a file over FTP.</fsummary> <desc><marker id="recv-2"/> <p>Fetches a file over FTP.</p> @@ -217,7 +215,7 @@ </func> <func> - <name>recv(Connection, RemoteFile, LocalFile) -> ok | {error, Reason}</name> + <name since="">recv(Connection, RemoteFile, LocalFile) -> ok | {error, Reason}</name> <fsummary>Fetches a file over FTP.</fsummary> <type> <v>Connection = connection()</v> @@ -232,7 +230,7 @@ </func> <func> - <name>send(Connection, LocalFile) -> ok | {error, Reason}</name> + <name since="">send(Connection, LocalFile) -> ok | {error, Reason}</name> <fsummary>Sends a file over FTP.</fsummary> <desc><marker id="send-2"/> <p>Sends a file over FTP.</p> @@ -245,7 +243,7 @@ </func> <func> - <name>send(Connection, LocalFile, RemoteFile) -> ok | {error, Reason}</name> + <name since="">send(Connection, LocalFile, RemoteFile) -> ok | {error, Reason}</name> <fsummary>Sends a file over FTP.</fsummary> <type> <v>Connection = connection()</v> @@ -260,7 +258,7 @@ </func> <func> - <name>type(Connection, Type) -> ok | {error, Reason}</name> + <name since="">type(Connection, Type) -> ok | {error, Reason}</name> <fsummary>Changes the file transfer type.</fsummary> <type> <v>Connection = connection()</v> diff --git a/lib/common_test/doc/src/ct_hooks.xml b/lib/common_test/doc/src/ct_hooks.xml index 12ec3bcec3..048552e4bb 100644 --- a/lib/common_test/doc/src/ct_hooks.xml +++ b/lib/common_test/doc/src/ct_hooks.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>PA1</rev> <file>ct_hooks.sgml</file> </header> - <module>ct_hooks</module> + <module since="OTP R14B02">ct_hooks</module> <modulesummary>A callback interface on top of Common Test.</modulesummary> <description> @@ -75,7 +75,7 @@ <funcs> <func> - <name>Module:init(Id, Opts) -> {ok, State} | {ok, State, Priority}</name> + <name since="OTP R14B02">Module:init(Id, Opts) -> {ok, State} | {ok, State, Priority}</name> <fsummary>Initiates the Common Test Hook.</fsummary> <type> <v>Id = reference() | term()</v> @@ -94,7 +94,7 @@ <seealso marker="#Module:id-1"><c>ct_hooks:id/1</c></seealso>, or a <c>reference</c> (created using <seealso marker="erts:erlang#make_ref-0">erlang:make_ref/0</seealso> - in <c>ERTS</c>) if + in ERTS) if <seealso marker="#Module:id-1"><c>ct_hooks:id/1</c></seealso> is not implemented.</p> @@ -109,7 +109,7 @@ </func> <func> - <name>Module:pre_init_per_suite(SuiteName, InitData, CTHState) -> Result</name> + <name since="OTP R14B02">Module:pre_init_per_suite(SuiteName, InitData, CTHState) -> Result</name> <fsummary>Called before init_per_suite.</fsummary> <type> <v>SuiteName = atom()</v> @@ -161,7 +161,7 @@ </func> <func> - <name>Module:post_init_per_suite(SuiteName, Config, Return, CTHState) -> Result</name> + <name since="OTP R14B02">Module:post_init_per_suite(SuiteName, Config, Return, CTHState) -> Result</name> <fsummary>Called after init_per_suite.</fsummary> <type> <v>SuiteName = atom()</v> @@ -208,9 +208,10 @@ </func> <func> - <name>Module:pre_init_per_group(GroupName, InitData, CTHState) -> Result</name> + <name since="OTP 19.3">Module:pre_init_per_group(SuiteName, GroupName, InitData, CTHState) -> Result</name> <fsummary>Called before init_per_group.</fsummary> <type> + <v>SuiteName = atom()</v> <v>GroupName = atom()</v> <v>InitData = Config | SkipOrFail</v> <v>Config = NewConfig = [{Key,Value}]</v> @@ -231,13 +232,19 @@ but for function <seealso marker="common_test#Module:init_per_group-2"><c>init_per_group</c></seealso> instead.</p> + + <p>If <c>Module:pre_init_per_group/4</c> is not exported, common_test + will attempt to call <c>Module:pre_init_per_group(GroupName, + InitData, CTHState)</c> instead. This is for backwards + compatibility.</p> </desc> </func> <func> - <name>Module:post_init_per_group(GroupName, Config, Return, CTHState) -> Result</name> + <name since="OTP 19.3">Module:post_init_per_group(SuiteName, GroupName, Config, Return, CTHState) -> Result</name> <fsummary>Called after init_per_group.</fsummary> <type> + <v>SuiteName = atom()</v> <v>GroupName = atom()</v> <v>Config = [{Key,Value}]</v> <v>Return = NewReturn = Config | SkipOrFail | term()</v> @@ -258,13 +265,19 @@ but for function <seealso marker="common_test#Module:init_per_group-2"><c>init_per_group</c></seealso> instead.</p> + + <p>If <c>Module:post_init_per_group/5</c> is not exported, common_test + will attempt to call <c>Module:post_init_per_group(GroupName, + Config, Return, CTHState)</c> instead. This is for backwards + compatibility.</p> </desc> </func> <func> - <name>Module:pre_init_per_testcase(TestcaseName, InitData, CTHState) -> Result</name> + <name since="OTP 19.3">Module:pre_init_per_testcase(SuiteName, TestcaseName, InitData, CTHState) -> Result</name> <fsummary>Called before init_per_testcase.</fsummary> <type> + <v>SuiteName = atom()</v> <v>TestcaseName = atom()</v> <v>InitData = Config | SkipOrFail</v> <v>Config = NewConfig = [{Key,Value}]</v> @@ -286,6 +299,11 @@ <seealso marker="common_test#Module:init_per_testcase-2"><c>init_per_testcase</c></seealso> instead.</p> + <p>If <c>Module:pre_init_per_testcase/4</c> is not exported, common_test + will attempt to call <c>Module:pre_init_per_testcase(TestcaseName, + InitData, CTHState)</c> instead. This is for backwards + compatibility.</p> + <p>CTHs cannot be added here right now. That feature may be added in a later release, but it would right now break backwards compatibility.</p> @@ -293,9 +311,10 @@ </func> <func> - <name>Module:post_init_per_testcase(TestcaseName, Config, Return, CTHState) -> Result</name> + <name since="OTP 19.3">Module:post_init_per_testcase(SuiteName, TestcaseName, Config, Return, CTHState) -> Result</name> <fsummary>Called after init_per_testcase.</fsummary> <type> + <v>SuiteName = atom()</v> <v>TestcaseName = atom()</v> <v>Config = [{Key,Value}]</v> <v>Return = NewReturn = Config | SkipOrFail | term()</v> @@ -316,15 +335,21 @@ but for function <seealso marker="common_test#Module:init_per_testcase-2"><c>init_per_testcase</c></seealso> instead.</p> + + <p>If <c>Module:post_init_per_testcase/5</c> is not exported, common_test + will attempt to call <c>Module:post_init_per_testcase(TestcaseName, + Config, Return, CTHState)</c> instead. This is for backwards + compatibility.</p> </desc> </func> <func> - <name>Module:pre_end_per_testcase(TestcaseName, InitData, CTHState) -> Result</name> + <name since="OTP 19.3">Module:pre_end_per_testcase(SuiteName, TestcaseName, EndData, CTHState) -> Result</name> <fsummary>Called before end_per_testcase.</fsummary> <type> + <v>SuiteName = atom()</v> <v>TestcaseName = atom()</v> - <v>InitData = Config</v> + <v>EndData = Config</v> <v>Config = NewConfig = [{Key,Value}]</v> <v>CTHState = NewCTHState = term()</v> <v>Result = {NewConfig, NewCTHState}</v> @@ -345,14 +370,20 @@ <p>This function can not change the result of the test case by returning skip or fail tuples, but it may insert items in <c>Config</c> that can be read in - <c>end_per_testcase/2</c> or in <c>post_end_per_testcase/4</c>.</p> + <c>end_per_testcase/2</c> or in <c>post_end_per_testcase/5</c>.</p> + + <p>If <c>Module:pre_end_per_testcase/4</c> is not exported, common_test + will attempt to call <c>Module:pre_end_per_testcase(TestcaseName, + EndData, CTHState)</c> instead. This is for backwards + compatibility.</p> </desc> </func> <func> - <name>Module:post_end_per_testcase(TestcaseName, Config, Return, CTHState) -> Result</name> + <name since="OTP 19.3">Module:post_end_per_testcase(SuiteName, TestcaseName, Config, Return, CTHState) -> Result</name> <fsummary>Called after end_per_testcase.</fsummary> <type> + <v>SuiteName = atom()</v> <v>TestcaseName = atom()</v> <v>Config = [{Key,Value}]</v> <v>Return = NewReturn = Config | SkipOrFail | term()</v> @@ -373,13 +404,19 @@ but for function <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso> instead.</p> + + <p>If <c>Module:post_end_per_testcase/5</c> is not exported, common_test + will attempt to call <c>Module:post_end_per_testcase(TestcaseName, + Config, Return, CTHState)</c> instead. This is for backwards + compatibility.</p> </desc> </func> <func> - <name>Module:pre_end_per_group(GroupName, EndData, CTHState) -> Result</name> + <name since="OTP 19.3">Module:pre_end_per_group(SuiteName, GroupName, EndData, CTHState) -> Result</name> <fsummary>Called before end_per_group.</fsummary> <type> + <v>SuiteName = atom()</v> <v>GroupName = atom()</v> <v>EndData = Config | SkipOrFail</v> <v>Config = NewConfig = [{Key,Value}]</v> @@ -400,13 +437,19 @@ but for function <seealso marker="common_test#Module:end_per_group-2"><c>end_per_group</c></seealso> instead.</p> + + <p>If <c>Module:pre_end_per_group/4</c> is not exported, common_test + will attempt to call <c>Module:pre_end_per_group(GroupName, + EndData, CTHState)</c> instead. This is for backwards + compatibility.</p> </desc> </func> <func> - <name>Module:post_end_per_group(GroupName, Config, Return, CTHState) -> Result</name> + <name since="OTP 19.3">Module:post_end_per_group(SuiteName, GroupName, Config, Return, CTHState) -> Result</name> <fsummary>Called after end_per_group.</fsummary> <type> + <v>SuiteName = atom()</v> <v>GroupName = atom()</v> <v>Config = [{Key,Value}]</v> <v>Return = NewReturn = Config | SkipOrFail | term()</v> @@ -427,11 +470,16 @@ but for function <seealso marker="common_test#Module:end_per_group-2">end_per_group</seealso> instead.</p> + + <p>If <c>Module:post_end_per_group/5</c> is not exported, common_test + will attempt to call <c>Module:post_end_per_group(GroupName, + Config, Return, CTHState)</c> instead. This is for backwards + compatibility.</p> </desc> </func> <func> - <name>Module:pre_end_per_suite(SuiteName, EndData, CTHState) -> Result</name> + <name since="OTP R14B02">Module:pre_end_per_suite(SuiteName, EndData, CTHState) -> Result</name> <fsummary>Called before end_per_suite.</fsummary> <type> <v>SuiteName = atom()</v> @@ -458,7 +506,7 @@ </func> <func> - <name>Module:post_end_per_suite(SuiteName, Config, Return, CTHState) -> Result</name> + <name since="OTP R14B02">Module:post_end_per_suite(SuiteName, Config, Return, CTHState) -> Result</name> <fsummary>Called after end_per_suite.</fsummary> <type> <v>SuiteName = atom()</v> @@ -485,9 +533,10 @@ </func> <func> - <name>Module:on_tc_fail(TestName, Reason, CTHState) -> NewCTHState</name> + <name since="OTP 19.3">Module:on_tc_fail(SuiteName, TestName, Reason, CTHState) -> NewCTHState</name> <fsummary>Called after the CTH scope ends.</fsummary> <type> + <v>SuiteName = atom()</v> <v>TestName = init_per_suite | end_per_suite | {init_per_group,GroupName} | {end_per_group,GroupName} | {FuncName,GroupName} | FuncName</v> <v>FuncName = atom()</v> <v>GroupName = atom()</v> @@ -505,7 +554,7 @@ <item><p>If <c>init_per_suite</c> fails, this function is called after <seealso marker="#Module:post_init_per_suite-4"><c>post_init_per_suite</c></seealso>.</p></item> <item><p>If a test case fails, this funcion is called after - <seealso marker="#Module:post_end_per_testcase-4"><c>post_end_per_testcase</c></seealso>.</p></item> + <seealso marker="#Module:post_end_per_testcase-5"><c>post_end_per_testcase</c></seealso>.</p></item> </list> <p>If the failed test case belongs to a test case group, the first @@ -519,13 +568,19 @@ For details, see section <seealso marker="event_handler_chapter#events">Event Handling</seealso> in the User's Guide.</p> + + <p>If <c>Module:on_tc_fail/4</c> is not exported, common_test + will attempt to call <c>Module:on_tc_fail(TestName, Reason, + CTHState)</c> instead. This is for backwards + compatibility.</p> </desc> </func> <func> - <name>Module:on_tc_skip(TestName, Reason, CTHState) -> NewCTHState</name> + <name since="OTP 19.3">Module:on_tc_skip(SuiteName, TestName, Reason, CTHState) -> NewCTHState</name> <fsummary>Called after the CTH scope ends.</fsummary> <type> + <v>SuiteName = atom()</v> <v>TestName = init_per_suite | end_per_suite | {init_per_group,GroupName} | {end_per_group,GroupName} | {FuncName,GroupName} | FuncName</v> <v>FuncName = atom()</v> <v>GroupName = atom()</v> @@ -542,9 +597,9 @@ <list type="bulleted"> <item><p>If <c>init_per_group</c> is skipped, this function is called after - <seealso marker="#Module:post_init_per_group-4"><c>post_init_per_group</c></seealso>.</p></item> + <seealso marker="#Module:post_init_per_group-5"><c>post_init_per_group</c></seealso>.</p></item> <item><p>If a test case is skipped, this function is called after - <seealso marker="#Module:post_end_per_testcase-4"><c>post_end_per_testcase</c></seealso>.</p></item> + <seealso marker="#Module:post_end_per_testcase-5"><c>post_end_per_testcase</c></seealso>.</p></item> </list> <p>If the skipped test case belongs to a test case group, the first @@ -559,11 +614,16 @@ For details, see section <seealso marker="event_handler_chapter#events">Event Handling</seealso> in the User's Guide.</p> + + <p>If <c>Module:on_tc_skip/4</c> is not exported, common_test + will attempt to call <c>Module:on_tc_skip(TestName, Reason, + CTHState)</c> instead. This is for backwards + compatibility.</p> </desc> </func> <func> - <name>Module:terminate(CTHState)</name> + <name since="OTP R14B02">Module:terminate(CTHState)</name> <fsummary>Called after the CTH scope ends.</fsummary> <type> <v>CTHState = term()</v> @@ -577,7 +637,7 @@ </func> <func> - <name>Module:id(Opts) -> Id</name> + <name since="OTP R14B02">Module:id(Opts) -> Id</name> <fsummary>Called before the init function of a CTH.</fsummary> <type> <v>Opts = term()</v> diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml index 3eb1945a61..ea4b67be08 100644 --- a/lib/common_test/doc/src/ct_hooks_chapter.xml +++ b/lib/common_test/doc/src/ct_hooks_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2011</year><year>2013</year> + <year>2011</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -38,7 +38,7 @@ extensions of the default behavior of <c>Common Test</c> using hooks before and after all test suite calls. CTHs allow advanced <c>Common Test</c> users to abstract out behavior that is common to multiple test suites - without littering all test suites with library calls. this can be used + without littering all test suites with library calls. This can be used for logging, starting, and monitoring external systems, building C files needed by the tests, and so on.</p> @@ -175,10 +175,10 @@ <row> <cell><seealso marker="common_test#Module:init_per_group-2"> init_per_group/2</seealso></cell> - <cell><seealso marker="ct_hooks#Module:post_init_per_group-4"> - post_init_per_group/4</seealso> is called</cell> - <cell><seealso marker="ct_hooks#Module:post_end_per_suite-4"> - post_end_per_group/4</seealso> has been called for that group</cell> + <cell><seealso marker="ct_hooks#Module:post_init_per_group-5"> + post_init_per_group/5</seealso> is called</cell> + <cell><seealso marker="ct_hooks#Module:post_end_per_group-5"> + post_end_per_group/5</seealso> has been called for that group</cell> </row> <tcaption>Scope of a CTH</tcaption> </table> @@ -245,16 +245,18 @@ </list> <p> - This is done in the CTH functions called pre_<name of function>. - These functions take the same three arguments, <c>Name</c>, + This is done in the CTH functions called <c>pre_<name of function></c>. + These functions take the arguments <c>SuiteName</c>, <c>Name</c> (group or test case name, if applicable), <c>Config</c>, and <c>CTHState</c>. The return value of the CTH function is always a combination of a result for the suite/group/test and an updated <c>CTHState</c>.</p> <p>To let the test suite continue on executing, return the configuration - list that you want the test to use as the result. To skip or - fail the test, return a tuple with <c>skip</c> or <c>fail</c>, and a reason - as the result.</p> + list that you want the test to use as the result.</p> + + <p>All pre hooks, except <c>pre_end_per_testcase/4</c>, can + skip or fail the test by returning a tuple with <c>skip</c> or + <c>fail</c>, and a reason as the result.</p> <p><em>Example:</em></p> <code> @@ -290,7 +292,7 @@ <p> This is done in the CTH functions called <c>post_<name of function></c>. - These functions take the same four arguments, <c>Name</c>, + These functions take the arguments <c>SuiteName</c>, <c>Name</c> (group or test case name, if applicable), <c>Config</c>, <c>Return</c>, and <c>CTHState</c>. <c>Config</c> in this case is the same <c>Config</c> as the testcase is called with. <c>Return</c> is the value returned by the testcase. If the testcase @@ -308,7 +310,7 @@ <p><em>Example:</em></p> <code> - post_end_per_testcase(_TC, Config, {'EXIT',{_,_}}, CTHState) -> + post_end_per_testcase(_Suite, _TC, Config, {'EXIT',{_,_}}, CTHState) -> case db:check_consistency() of true -> %% DB is good, pass the test. @@ -317,7 +319,7 @@ %% DB is not good, mark as skipped instead of failing {{skip, "DB is inconsisten!"}, CTHState} end; - post_end_per_testcase(_TC, Config, Return, CTHState) -> + post_end_per_testcase(_Suite, _TC, Config, Return, CTHState) -> %% Do nothing if tc does not crash. {Return, CTHState}.</code> @@ -331,8 +333,8 @@ <title>Skip and Fail Hooks</title> <p> After any post hook has been executed for all installed CTHs, - <seealso marker="ct_hooks#Module:on_tc_fail-3">on_tc_fail</seealso> - or <seealso marker="ct_hooks#Module:on_tc_skip-3">on_tc_skip</seealso> + <seealso marker="ct_hooks#Module:on_tc_fail-4">on_tc_fail</seealso> + or <seealso marker="ct_hooks#Module:on_tc_skip-4">on_tc_skip</seealso> is called if the testcase failed or was skipped, respectively. You cannot affect the outcome of the tests any further at this point. </p> @@ -374,10 +376,10 @@ <title>Example CTH</title> <p>The following CTH logs information about a test run into a format parseable by <seealso marker="kernel:file#consult-1">file:consult/1</seealso> - (in <c>Kernel</c>): + (in Kernel): </p> <code> - %%% @doc Common Test Example Common Test Hook module. + %%% Common Test Example Common Test Hook module. -module(example_cth). %% Callbacks @@ -389,95 +391,95 @@ -export([pre_end_per_suite/3]). -export([post_end_per_suite/4]). - -export([pre_init_per_group/3]). - -export([post_init_per_group/4]). - -export([pre_end_per_group/3]). - -export([post_end_per_group/4]). + -export([pre_init_per_group/4]). + -export([post_init_per_group/5]). + -export([pre_end_per_group/4]). + -export([post_end_per_group/5]). - -export([pre_init_per_testcase/3]). - -export([post_init_per_testcase/4]). - -export([pre_end_per_testcase/3]). - -export([post_end_per_testcase/4]). + -export([pre_init_per_testcase/4]). + -export([post_init_per_testcase/5]). + -export([pre_end_per_testcase/4]). + -export([post_end_per_testcase/5]). - -export([on_tc_fail/3]). - -export([on_tc_skip/3]). + -export([on_tc_fail/4]). + -export([on_tc_skip/4]). -export([terminate/1]). -record(state, { file_handle, total, suite_total, ts, tcs, data }). - %% @doc Return a unique id for this CTH. + %% Return a unique id for this CTH. id(Opts) -> proplists:get_value(filename, Opts, "/tmp/file.log"). - %% @doc Always called before any other callback function. Use this to initiate + %% Always called before any other callback function. Use this to initiate %% any common state. init(Id, Opts) -> {ok,D} = file:open(Id,[write]), {ok, #state{ file_handle = D, total = 0, data = [] }}. - %% @doc Called before init_per_suite is called. + %% Called before init_per_suite is called. pre_init_per_suite(Suite,Config,State) -> {Config, State#state{ suite_total = 0, tcs = [] }}. - %% @doc Called after init_per_suite. + %% Called after init_per_suite. post_init_per_suite(Suite,Config,Return,State) -> {Return, State}. - %% @doc Called before end_per_suite. + %% Called before end_per_suite. pre_end_per_suite(Suite,Config,State) -> {Config, State}. - %% @doc Called after end_per_suite. + %% Called after end_per_suite. post_end_per_suite(Suite,Config,Return,State) -> Data = {suites, Suite, State#state.suite_total, lists:reverse(State#state.tcs)}, {Return, State#state{ data = [Data | State#state.data] , total = State#state.total + State#state.suite_total } }. - %% @doc Called before each init_per_group. - pre_init_per_group(Group,Config,State) -> + %% Called before each init_per_group. + pre_init_per_group(Suite,Group,Config,State) -> {Config, State}. - %% @doc Called after each init_per_group. - post_init_per_group(Group,Config,Return,State) -> + %% Called after each init_per_group. + post_init_per_group(Suite,Group,Config,Return,State) -> {Return, State}. - %% @doc Called before each end_per_group. - pre_end_per_group(Group,Config,State) -> + %% Called before each end_per_group. + pre_end_per_group(Suite,Group,Config,State) -> {Config, State}. - %% @doc Called after each end_per_group. - post_end_per_group(Group,Config,Return,State) -> + %% Called after each end_per_group. + post_end_per_group(Suite,Group,Config,Return,State) -> {Return, State}. - %% @doc Called before each init_per_testcase. - pre_init_per_testcase(TC,Config,State) -> + %% Called before each init_per_testcase. + pre_init_per_testcase(Suite,TC,Config,State) -> {Config, State#state{ ts = now(), total = State#state.suite_total + 1 } }. %% Called after each init_per_testcase (immediately before the test case). - post_init_per_testcase(TC,Config,Return,State) -> + post_init_per_testcase(Suite,TC,Config,Return,State) -> {Return, State} -%% @doc Called before each end_per_testcase (immediately after the test case). - pre_end_per_testcase(TC,Config,State) -> +%% Called before each end_per_testcase (immediately after the test case). + pre_end_per_testcase(Suite,TC,Config,State) -> {Config, State}. - %% @doc Called after each end_per_testcase. - post_end_per_testcase(TC,Config,Return,State) -> - TCInfo = {testcase, TC, Return, timer:now_diff(now(), State#state.ts)}, + %% Called after each end_per_testcase. + post_end_per_testcase(Suite,TC,Config,Return,State) -> + TCInfo = {testcase, Suite, TC, Return, timer:now_diff(now(), State#state.ts)}, {Return, State#state{ ts = undefined, tcs = [TCInfo | State#state.tcs] } }. - %% @doc Called after post_init_per_suite, post_end_per_suite, post_init_per_group, + %% Called after post_init_per_suite, post_end_per_suite, post_init_per_group, %% post_end_per_group and post_end_per_testcase if the suite, group or test case failed. - on_tc_fail(TC, Reason, State) -> + on_tc_fail(Suite, TC, Reason, State) -> State. - %% @doc Called when a test case is skipped by either user action + %% Called when a test case is skipped by either user action %% or due to an init function failing. - on_tc_skip(TC, Reason, State) -> + on_tc_skip(Suite, TC, Reason, State) -> State. - %% @doc Called when the scope of the CTH is done + %% Called when the scope of the CTH is done terminate(State) -> io:format(State#state.file_handle, "~p.~n", [{test_run, State#state.total, State#state.data}]), @@ -499,13 +501,14 @@ <tag><c>cth_log_redirect</c></tag> <item> <p>Built-in</p> - <p>Captures all <c>error_logger</c> and <c>SASL</c> logging - events and prints them to the current test case log. If an event cannot be - associated with a test case, it is printed in the <c>Common Test</c> framework log. + <p>Captures all log events that would normally be printed by the default + logger handler, and prints them to the current test case log. + If an event cannot be associated with a test case, it is printed in + the <c>Common Test</c> framework log. This happens for test cases running in parallel and events occuring in-between test cases. You can configure the level of - <seealso marker="sasl:sasl_app"><c>SASL</c></seealso> events report - using the normal <c>SASL</c> mechanisms.</p> + <seealso marker="sasl:sasl_app">SASL</seealso> reports + using the normal SASL mechanisms.</p> </item> <tag><c>cth_surefire</c></tag> <item> diff --git a/lib/common_test/doc/src/ct_master.xml b/lib/common_test/doc/src/ct_master.xml index 06f9b04f1b..2ab421fe9e 100644 --- a/lib/common_test/doc/src/ct_master.xml +++ b/lib/common_test/doc/src/ct_master.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>ct_master.xml</file> </header> - <module>ct_master</module> + <module since="">ct_master</module> <modulesummary>Distributed test execution control for Common Test.</modulesummary> <description> @@ -46,7 +46,7 @@ <funcs> <func> - <name>abort() -> ok</name> + <name since="">abort() -> ok</name> <fsummary>Stops all running tests.</fsummary> <desc><marker id="abort-0"/> <p>Stops all running tests.</p> @@ -54,7 +54,7 @@ </func> <func> - <name>abort(Nodes) -> ok</name> + <name since="">abort(Nodes) -> ok</name> <fsummary>Stops tests on specified nodes.</fsummary> <type> <v>Nodes = atom() | [atom()]</v> @@ -65,7 +65,7 @@ </func> <func> - <name>basic_html(Bool) -> ok</name> + <name since="OTP R15B01">basic_html(Bool) -> ok</name> <fsummary>If set to true, the ct_master logs are written on a primitive HTML format, not using the <c>Common Test</c> CSS style sheet.</fsummary> <type> @@ -79,7 +79,7 @@ </func> <func> - <name>get_event_mgr_ref() -> MasterEvMgrRef</name> + <name since="OTP 17.5">get_event_mgr_ref() -> MasterEvMgrRef</name> <fsummary>Gets a reference to the <c>Common Test</c> master event manager.</fsummary> <type> @@ -98,7 +98,7 @@ </func> <func> - <name>progress() -> [{Node, Status}]</name> + <name since="">progress() -> [{Node, Status}]</name> <fsummary>Returns test progress.</fsummary> <type> <v>Node = atom()</v> @@ -112,7 +112,7 @@ </func> <func> - <name>run(TestSpecs) -> ok</name> + <name since="">run(TestSpecs) -> ok</name> <fsummary>Equivalent to run(TestSpecs, false, [], []).</fsummary> <type> <v>TestSpecs = string() | [SeparateOrMerged]</v> @@ -124,7 +124,7 @@ </func> <func> - <name>run(TestSpecs, InclNodes, ExclNodes) -> ok</name> + <name since="">run(TestSpecs, InclNodes, ExclNodes) -> ok</name> <fsummary>Equivalent to run(TestSpecs, false, InclNodes, ExclNodes). </fsummary> <type> @@ -140,7 +140,7 @@ </func> <func> - <name>run(TestSpecs, AllowUserTerms, InclNodes, ExclNodes) -> ok</name> + <name since="">run(TestSpecs, AllowUserTerms, InclNodes, ExclNodes) -> ok</name> <fsummary>Tests are spawned on the nodes as specified in TestSpecs. </fsummary> <type> @@ -162,7 +162,7 @@ </func> <func> - <name>run_on_node(TestSpecs, Node) -> ok</name> + <name since="">run_on_node(TestSpecs, Node) -> ok</name> <fsummary>Equivalent to run_on_node(TestSpecs, false, Node).</fsummary> <type> <v>TestSpecs = string() | [SeparateOrMerged]</v> @@ -177,7 +177,7 @@ </func> <func> - <name>run_on_node(TestSpecs, AllowUserTerms, Node) -> ok</name> + <name since="">run_on_node(TestSpecs, AllowUserTerms, Node) -> ok</name> <fsummary>Tests are spawned on Node according to TestSpecs.</fsummary> <type> <v>TestSpecs = string() | [SeparateOrMerged]</v> @@ -191,7 +191,7 @@ </func> <func> - <name>run_test(Node, Opts) -> ok</name> + <name since="">run_test(Node, Opts) -> ok</name> <fsummary>Tests are spawned on Node using ct:run_test/1.</fsummary> <type> <v>Node = atom()</v> diff --git a/lib/common_test/doc/src/ct_master_chapter.xml b/lib/common_test/doc/src/ct_master_chapter.xml index 99555164e0..7b5aae7ad8 100644 --- a/lib/common_test/doc/src/ct_master_chapter.xml +++ b/lib/common_test/doc/src/ct_master_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2006</year><year>2013</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/ct_netconfc.xml b/lib/common_test/doc/src/ct_netconfc.xml index d8c82c7f2c..8fbe5f3df6 100644 --- a/lib/common_test/doc/src/ct_netconfc.xml +++ b/lib/common_test/doc/src/ct_netconfc.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,16 +32,38 @@ <rev>A</rev> <file>ct_netconfc.xml</file> </header> - <module>ct_netconfc</module> + <module since="OTP R15B02">ct_netconfc</module> <modulesummary>NETCONF client module.</modulesummary> -<description> + <description> <p>NETCONF client module.</p> <p>The NETCONF client is compliant with RFC 4741 NETCONF Configuration Protocol and RFC 4742 Using the NETCONF Configuration Protocol over - Secure SHell (SSH)..</p> + Secure SHell (SSH).</p> + + <marker id="Connecting"/> + <p><em>Connecting to a NETCONF server</em></p> + + <p>NETCONF sessions can either be opened by a single call + to <seealso marker="#open-1"><c>open/1,2</c></seealso> or by a call + to <seealso marker="#connect-1"><c>connect/1,2</c></seealso> followed + by one or more calls to + <seealso marker="#session-1"><c>session/1,2,3</c></seealso>.</p> + + <p>The properties of the sessions will be exactly the same, except + that when + using <seealso marker="#connect-1"><c>connect/1,2</c></seealso>, you + may start multiple sessions over the same SSH connection. Each + session is implemented as an SSH channel.</p> + + <p><seealso marker="#open-1"><c>open/1,2</c></seealso> will establish one + SSH connection with one SSH channel implementing one NETCONF + session. You may start mutiple sessions by + calling <seealso marker="#open-1"><c>open/1,2</c></seealso> multiple + times, but then a new SSH connection will be established for each + session.</p> <p>For each server to test against, the following entry can be added to a configuration file:</p> @@ -49,23 +71,21 @@ <pre> {server_id(),options()}.</pre> - <p>The <c>server_id()</c> or an associated <c>target_name()</c> (see - module <seealso marker="ct"><c>ct</c></seealso>) must then be used - in calls to - <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>.</p> + <p>The <seealso marker="#type-server_id"><c>server_id()</c></seealso> + or an associated + <seealso marker="ct#type-target_name"><c>ct:target_name()</c></seealso> + must then be used in calls to + <seealso marker="#connect-2"><c>connect/2</c></seealso> + or <seealso marker="#open-2"><c>open/2</c></seealso>.</p> - <p>If no configuration exists for a server, a session can still be - opened by calling - <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso> with - all necessary options specified in the call. The first argument to - <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso> can - then be any atom.</p> + <p>If no configuration exists for a server, + use <seealso marker="#connect-1"><c>connect/1</c></seealso> + or <seealso marker="#open-1"><c>open/1</c></seealso> instead, + and specify all necessary options in the <c>Options</c> parameter.</p> - </description> + <marker id="Logging"/> + <p><em>Logging</em></p> - <section> - <marker id="Logging"/> - <title>Logging</title> <p>The NETCONF server uses <c>error_logger</c> for logging of NETCONF traffic. A special purpose error handler is implemented in <c>ct_conn_log_h</c>. To use this error handler, add the @@ -73,9 +93,9 @@ <pre> suite() -> - [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].</pre> + [{ct_hooks, [{cth_conn_log, [{<seealso marker="ct#type-conn_log_mod"><c>ct:conn_log_mod()</c></seealso>,<seealso marker="ct#type-conn_log_options"><c>ct:conn_log_options()</c></seealso>}]}]}].</pre> - <p><c>conn_mod()</c> is the name of the <c>Common Test</c> module + <p><c>conn_log_mod()</c> is the name of the <c>Common Test</c> module implementing the connection protocol, for example, <c>ct_netconfc</c>.</p> <p>Hook option <c>log_type</c> specifies the type of logging:</p> @@ -84,7 +104,7 @@ <tag><c>raw</c></tag> <item><p>The sent and received NETCONF data is logged to a separate text file "as is" without any formatting. A link to the file is - added to the test case HTML log.</p>.</item> + added to the test case HTML log.</p></item> <tag><c>pretty</c></tag> <item><p>The sent and received NETCONF data is logged to a separate @@ -104,7 +124,7 @@ To do this, use hook option <c>hosts</c> and list the names of the servers/connections to be used in the suite. The connections must be named for this to work, that is, they must be opened with - <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>.</p> + <seealso marker="#open-2"><c>open/2</c></seealso>.</p> <p>Option <c>hosts</c> has no effect if <c>log_type</c> is set to <c>html</c> or <c>silent</c>.</p> @@ -113,13 +133,13 @@ configuration variable <c>ct_conn_log</c>:</p> <pre> - {ct_conn_log,[{conn_mod(),hook_options()}]}.</pre> + {ct_conn_log,[{<seealso marker="ct#type-conn_log_mod"><c>ct:conn_log_mod()</c></seealso>,<seealso marker="ct#type-conn_log_options"><c>ct:conn_log_options()</c></seealso>}]}.</pre> <p>For example:</p> <pre> {ct_conn_log,[{ct_netconfc,[{log_type,pretty}, - {hosts,[key_or_name()]}]}]}</pre> + {hosts,[<seealso marker="ct#type-key_or_name"><c>ct:key_or_name()</c></seealso>]}]}]}</pre> <note> <p>Hook options specified in a configuration file overwrite the @@ -164,170 +184,149 @@ <p>The same <c>ct_hooks</c> statement without the configuration file would cause HTML logging of all NETCONF connections in to the test case HTML log.</p> - </section> - <section> - <marker id="Notifications"/> - <title>Notifications</title> + <marker id="Notifications"/> + <p><em>Notifications</em></p> <p>The NETCONF client is also compliant with RFC 5277 NETCONF Event Notifications, which defines a mechanism for an asynchronous message notification delivery service for the NETCONF protocol.</p> <p>Specific functions to support this are - <seealso marker="#create_subscription-6"><c>ct_netconfc:create_subscription/6</c></seealso> + <seealso marker="#create_subscription-1"><c>create_subscription/1-6</c></seealso> and - <seealso marker="#get_event_streams-3"><c>ct_netconfc:get_event_streams/3</c></seealso>. - (The functions also exist with other arities.)</p> - </section> - - <section> - <title>Data Types</title> - <marker id="types"/> - <taglist> - <tag><c>client() = handle() | key_or_name()</c></tag> - <item><marker id="type-client"/> - <p>For <c>handle()</c>, see module - <seealso marker="ct"><c>ct</c></seealso>.</p></item> - - <tag><c>error_reason() = term()</c></tag> - <item><marker id="type-error_reason"/> </item> - <tag><c>event_time() = {eventTime, xml_attributes(), [xs_datetime()]}</c></tag> - <item><marker id="type-event_time"/> </item> - - <tag><c>handle() = term()</c></tag> - <item><marker id="type-handle"/> - <p>Opaque reference for a connection (NETCONF session). For more - information, see module <seealso marker="ct"><c>ct</c></seealso>.</p> - </item> - - <tag><c>host() = <seealso marker="kernel:inet#type-hostname"><c>inet:hostname()</c></seealso> | <seealso marker="kernel:inet#type-ip_address"><c>inet:ip_address()</c></seealso></c></tag> - <item><marker id="type-host"/></item> - - <tag><c>key_or_name() = server_id() | target_name()</c></tag> - <item><marker id="type-key_or_name"/> - <p>For <c>target_name</c>, see module - <seealso marker="ct"><c>ct</c></seealso>.</p></item> - - <tag><c>netconf_db() = running | startup | candidate</c></tag> - <item><marker id="type-netconf_db"/> </item> + <seealso marker="#get_event_streams-1"><c>get_event_streams/1-3</c></seealso>.</p> - <tag><c>notification() = {notification, xml_attributes(), notification_content()}</c></tag> - <item><marker id="type-notification"/> </item> + <marker id="Default_timeout"/> + <p><em>Default Timeout</em></p> - <tag><c>notification_content() = [event_time() | simple_xml()]</c></tag> - <item><marker id="type-notification_content"/> </item> + <p>Most of the functions in this module have one variant with + a <c>Timeout</c> parameter, and one without. If nothing else is + specified, the default value <c>infinity</c> is used when + the <c>Timeout</c> parameter is not given.</p> - <tag><c>option() = {ssh, host()} | {port, <seealso marker="kernel:inet#type-port_number"><c>inet:port_number()</c></seealso>} | {timeout, timeout()} | SshConnectOption</c></tag> - <item><marker id="type-option"/> + </description> + <datatypes> + <datatype> + <name name="client"/> + </datatype> + <datatype> + <name name="error_reason"/> + </datatype> + <datatype> + <name name="event_time"/> + </datatype> + <datatype> + <name name="handle"/> + <desc> + <p>Opaque reference for a connection to a NETCONF server or a + NETCONF session.</p> + </desc> + </datatype> + <datatype> + <name name="host"/> + </datatype> + <datatype> + <name name="netconf_db"/> + </datatype> + <datatype> + <name name="notification"/> + </datatype> + <datatype> + <name name="notification_content"/> + </datatype> + <datatype> + <name name="option"/> + <desc> <p><c>SshConnectOption</c> is any valid option to <seealso marker="ssh:ssh#connect-3"><c>ssh:connect/3,4</c></seealso>. Common options used are <c>user</c>, <c>password</c> and <c>user_dir</c>. The <c>SshConnectOptions</c> are - verfied by the SSH application.</p></item> - - <tag><c>options() = [option()]</c></tag> - <item><marker id="type-options"/> - <p>Options used for setting up an SSH connection to a NETCONF - server.</p></item> - - <tag><c>server_id() = atom()</c></tag> - <item><marker id="type-server_id"/> + verfied by the SSH application.</p> + </desc> + </datatype> + <datatype> + <name name="options"/> + <desc> + <p>Options used for setting up an SSH connection to a NETCONF + server.</p> + </desc> + </datatype> + <datatype> + <name name="server_id"/> + <desc> <p>The identity of a server, specified in a configuration - file.</p></item> - - <tag><c>simple_xml() = {xml_tag(), xml_attributes(), xml_content()} | {xml_tag(), xml_content()} | xml_tag()</c></tag> - <item><marker id="type-simple_xml"/> - <p>This type is further described in application - <seealso marker="xmerl:index"><c>xmerl</c></seealso>.</p></item> - - <tag><c>stream_data() = {description, string()} | {replaySupport, string()} | {replayLogCreationTime, string()} | {replayLogAgedTime, string()}</c></tag> - <item><marker id="type-stream_data"/> - <p>For details about the data format for the string values, see - "XML Schema for Event Notifications" in RFC 5277.</p></item> - - <tag><c>stream_name() = string()</c></tag> - <item><marker id="type-stream_name"/> </item> - - <tag><c>streams() = [{stream_name(), [stream_data()]}]</c></tag> - <item><marker id="type-streams"/> </item> - - <tag><c>xml_attribute_tag() = atom()</c></tag> - <item><marker id="type-xml_attribute_tag"/> </item> - - <tag><c>xml_attribute_value() = string()</c></tag> - <item><marker id="type-xml_attribute_value"/> </item> - - <tag><c>xml_attributes() = [{xml_attribute_tag(), xml_attribute_value()}]</c></tag> - <item><marker id="type-xml_attributes"/> </item> - - <tag><c>xml_content() = [simple_xml() | iolist()]</c></tag> - <item><marker id="type-xml_content"/> </item> - - <tag><c>xml_tag() = atom()</c></tag> - <item><marker id="type-xml_tag"/> </item> - - <tag><c>xpath() = {xpath, string()}</c></tag> - <item><marker id="type-xpath"/> </item> - - <tag><c>xs_datetime() = string()</c></tag> - <item><marker id="type-xs_datetime"/> - <p>This date and time identifier has the same format as the XML type + file.</p> + </desc> + </datatype> + <datatype> + <name name="simple_xml"/> + <desc> + <p>This type is further described in application + <seealso marker="xmerl:index"><c>xmerl</c></seealso>.</p> + </desc> + </datatype> + <datatype> + <name name="stream_data"/> + <desc> + <p>For details about the data format for the string values, see + "XML Schema for Event Notifications" in RFC 5277.</p> + </desc> + </datatype> + <datatype> + <name name="stream_name"/> + </datatype> + <datatype> + <name name="streams"/> + </datatype> + <datatype> + <name name="xml_attribute_tag"/> + </datatype> + <datatype> + <name name="xml_attribute_value"/> + </datatype> + <datatype> + <name name="xml_attributes"/> + </datatype> + <datatype> + <name name="xml_content"/> + </datatype> + <datatype> + <name name="xml_tag"/> + </datatype> + <datatype> + <name name="xpath"/> + </datatype> + <datatype> + <name name="xs_datetime"/> + <desc> + <p>This date and time identifier has the same format as the XML type <c>dateTime</c> and is compliant with RFC 3339 Date and Time on the Internet Timestamps. The format is as follows:</p> - <pre> + <pre> [-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]</pre> - </item> - </taglist> - </section> - - <funcs> - <func> - <name>action(Client, Action) -> Result</name> - <fsummary>Equivalent to action(Client, Action, infinity).</fsummary> - <desc><marker id="action-2"/> - <p>Equivalent to - <seealso marker="#action-3"><c>ct_netconfc:action(Client, Action, - infinity)</c></seealso>.</p> </desc> - </func> + </datatype> + </datatypes> + <funcs> <func> - <name>action(Client, Action, Timeout) -> Result</name> + <name name="action" arity="2" since="OTP R15B02"/> + <name name="action" arity="3" since="OTP R15B02"/> <fsummary>Executes an action.</fsummary> - <type> - <v>Client = client()</v> - <v>Action = simple_xml()</v> - <v>Timeout = timeout()</v> - <v>Result = ok | {ok, [simple_xml()]} | {error, error_reason()}</v> - </type> - <desc><marker id="action-3"/> + <desc> <p>Executes an action. If the return type is void, <c>ok</c> is returned instead of <c>{ok,[simple_xml()]}</c>.</p> </desc> </func> <func> - <name>close_session(Client) -> Result</name> - <fsummary>Equivalent to close_session(Client, infinity).</fsummary> - <desc><marker id="close_session-1"/> - <p>Equivalent to - <seealso marker="#close_session-2"><c>ct_netconfc:close_session(Client, - infinity)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>close_session(Client, Timeout) -> Result</name> + <name name="close_session" arity="1" since="OTP R15B02"/> + <name name="close_session" arity="2" since="OTP R15B02"/> <fsummary>Requests graceful termination of the session associated with the client.</fsummary> - <type> - <v>Client = client()</v> - <v>Timeout = timeout()</v> - <v>Result = ok | {error, error_reason()}</v> - </type> - <desc><marker id="close_session-2"/> + <desc> <p>Requests graceful termination of the session associated with the client.</p> @@ -340,115 +339,148 @@ </func> <func> - <name>copy_config(Client, Source, Target) -> Result</name> - <fsummary>Equivalent to copy_config(Client, Source, Target, - infinity).</fsummary> - <desc><marker id="copy_config-3"/> - <p>Equivalent to - <seealso marker="#copy_config-4"><c>ct_netconfc:copy_config(Client, - Source, Target, infinity)</c></seealso>.</p> - </desc> - </func> + <name name="connect" arity="1" since="OTP 20.0"/> + <fsummary>Opens an SSH connection to a NETCONF server.</fsummary> + <desc> + <p>Opens an SSH connection to a NETCONF server.</p> - <func> - <name>copy_config(Client, Target, Source, Timeout) -> Result</name> - <fsummary>Copies configuration data.</fsummary> - <type> - <v>Client = client()</v> - <v>Target = netconf_db()</v> - <v>Source = netconf_db()</v> - <v>Timeout = timeout()</v> - <v>Result = ok | {error, error_reason()}</v> - </type> - <desc><marker id="copy_config-4"/> - <p>Copies configuration data.</p> + <p>If the server options are specified in a configuration file, use + <seealso marker="#connect-2"><c>connect/2</c></seealso> + instead.</p> - <p>Which source and target options that can be issued depends on the - capabilities supported by the server. That is, <c>:candidate</c> - and/or <c>:startup</c> are required.</p> + <p>The opaque <seealso marker="#type-handle"><c>handle()</c></seealso> + reference returned from this + function is required as connection identifier when opening + sessions over this connection, see + <seealso marker="#session-1"><c>session/1,2,3</c></seealso>.</p> + + <p>Option <c>timeout</c> (milliseconds) is used when setting up the + SSH connection. It is not used for any other purposes during the + lifetime of the connection.</p> </desc> </func> <func> - <name>create_subscription(Client) -> term()</name> - <fsummary>Creates a subscription for event notifications.</fsummary> - <desc><marker id="create_subscription-1"/></desc> - </func> + <name name="connect" arity="2" since="OTP 20.0"/> + <fsummary>Opens an SSH connection to a named NETCONF server.</fsummary> + <desc> + <p>Open an SSH connection to a named NETCONF server.</p> - <func> - <name>create_subscription(Client, Timeout) -> term()</name> - <fsummary>Creates a subscription for event notifications.</fsummary> - <desc><marker id="create_subscription-2"/></desc> - </func> + <p>If <c><anno>KeyOrName</anno></c> is a + configured <c>server_id()</c> or a + <c>target_name()</c> associated with such an Id, then the options + for this server are fetched from the configuration file.</p> - <func> - <name>create_subscription(Client, Stream, Timeout) -> term()</name> - <fsummary>Creates a subscription for event notifications.</fsummary> - <desc><marker id="create_subscription-3"/></desc> - </func> + <p>Argument <c><anno>ExtraOptions</anno></c> is added to the + options found in the configuration file. If the same options + are specified, the values from the configuration file + overwrite <c><anno>ExtraOptions</anno></c>.</p> - <func> - <name>create_subscription(Client, StartTime, StopTime, Timeout) -> term()</name> - <fsummary>Creates a subscription for event notifications.</fsummary> - <desc><marker id="create_subscription-4"/></desc> + <p>If the server is not specified in a configuration file, use + <seealso marker="#connect-1"><c>connect/1</c></seealso> + instead.</p> + + <p>The opaque <seealso marker="#type-handle"><c>handle()</c></seealso> + reference returned from this + function can be used as connection identifier when opening + sessions over this connection, see + <seealso marker="#session-1"><c>session/1,2,3</c></seealso>. + However, if <c><anno>KeyOrName</anno></c> is a + <c>target_name()</c>, that is, if the server is named through a + call to <seealso marker="ct#require-2"><c>ct:require/2</c></seealso> + or a <c>require</c> statement in the test suite, then this name can + be used instead of + <seealso marker="#type-handle"><c>handle()</c></seealso>.</p> + + <p>Option <c>timeout</c> (milliseconds) is used when setting up the + SSH connection. It is not used for any other purposes during the + lifetime of the connection.</p> + </desc> </func> <func> - <name>create_subscription(Client, Stream, StartTime, StopTime, Timeout) -> term()</name> - <fsummary>Creates a subscription for event notifications.</fsummary> - <desc><marker id="create_subscription-5"/></desc> + <name name="copy_config" arity="3" since="OTP R15B02"/> + <name name="copy_config" arity="4" since="OTP R15B02"/> + <fsummary>Copies configuration data.</fsummary> + <desc> + <p>Copies configuration data.</p> + + <p>Which source and target options that can be issued depends on the + capabilities supported by the server. That is, <c>:candidate</c> + and/or <c>:startup</c> are required.</p> + </desc> </func> <func> - <name>create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout) -> Result</name> + <name since="OTP R15B02">create_subscription(Client) -> Result</name> + <name since="OTP R15B02">create_subscription(Client, Stream) -> Result</name> + <name since="OTP R15B02">create_subscription(Client, Stream, Filter) -> Result</name> + <name since="OTP R15B02">create_subscription(Client, Stream, Filter, Timeout) -> Result</name> + <name name="create_subscription" arity="5" clause_i="2" since="OTP R15B02"/> + <name name="create_subscription" arity="6" since="OTP R15B02"/> <fsummary>Creates a subscription for event notifications.</fsummary> - <type> - <v>Client = client()</v> - <v>Stream = stream_name()</v> - <v>Filter = simple_xml() | [simple_xml()]</v> - <v>StartTime = xs_datetime()</v> - <v>StopTime = xs_datetime()</v> - <v>Timeout = timeout()</v> - <v>Result = ok | {error, error_reason()}</v> - </type> - <desc><marker id="create_subscription-6"/> + <desc> <p>Creates a subscription for event notifications.</p> <p>This function sets up a subscription for NETCONF event notifications of the specified stream type, matching the specified filter. The calling process receives notifications as messages of - type <c>notification()</c>.</p> + type <seealso marker="#type-notification"><c>notification()</c></seealso>.</p> + + <p>Only a subset of the function clauses are show above. The + full set of valid combinations of input parameters is as + follows:</p> + +<pre>create_subscription(Client) + +create_subscription(Client, Timeout) +create_subscription(Client, Stream) +create_subscription(Client, Filter) + +create_subscription(Client, Stream, Timeout) +create_subscription(Client, Filter, Timeout) +create_subscription(Client, Stream, Filter) +create_subscription(Client, StartTime, StopTime) + +create_subscription(Client, Stream, Filter, Timeout) +create_subscription(Client, StartTime, StopTime, Timeout) +create_subscription(Client, Stream, StartTime, StopTime) +create_subscription(Client, Filter, StartTime, StopTime) + +create_subscription(Client, Stream, StartTime, StopTime, Timeout) +create_subscription(Client, Stream, Filter, StartTime, StopTime) +create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout)</pre> <taglist> - <tag><c>Stream</c></tag> + <tag><c><anno>Stream</anno></c></tag> <item><p>Optional parameter that indicates which stream of event is of interest. If not present, events in the default NETCONF stream are sent.</p></item> - <tag><c>Filter</c></tag> + <tag><c><anno>Filter</anno></c></tag> <item><p>Optional parameter that indicates which subset of all possible events is of interest. The parameter format is the same as that of the filter parameter in the NETCONF protocol operations. If not present, all events not precluded by other parameters are sent.</p></item> - <tag><c>StartTime</c></tag> + <tag><c><anno>StartTime</anno></c></tag> <item><p>Optional parameter used to trigger the replay feature and indicate that the replay is to start at the time specified. - If <c>StartTime</c> is not present, this is not a replay - subscription.</p> + If <c><anno>StartTime</anno></c> is not present, this is not a + replay subscription.</p> <p>It is not valid to specify start times that are later than - the current time. If <c>StartTime</c> is specified earlier - than the log can support, the replay begins with the earliest - available notification.</p> + the current time. If <c><anno>StartTime</anno></c> is specified + earlier than the log can support, the replay begins with the + earliest available notification.</p> <p>This parameter is of type <c>dateTime</c> and compliant to RFC 3339. Implementations must support time zones.</p></item> - <tag><c>StopTime</c></tag> + <tag><c><anno>StopTime</anno></c></tag> <item><p>Optional parameter used with the optional replay feature to indicate the newest notifications of interest. If - <c>StopTime</c> is not present, the notifications continues - until the subscription is terminated.</p> + <c><anno>StopTime</anno></c> is not present, the notifications + continues until the subscription is terminated.</p> <p>Must be used with and be later than <c>StartTime</c>. Values - of <c>StopTime</c> in the future are valid. This parameter is - of type <c>dateTime</c> and compliant to RFC 3339. + of <c><anno>StopTime</anno></c> in the future are valid. This + parameter is of type <c>dateTime</c> and compliant to RFC 3339. Implementations must support time zones.</p></item> </taglist> @@ -458,25 +490,10 @@ </func> <func> - <name>delete_config(Client, Target) -> Result</name> - <fsummary>Equivalent to delete_config(Client, Target, - infinity).</fsummary> - <desc><marker id="delete_config-2"/> - <p>Equivalent to - <seealso marker="#delete_config-3"><c>ct_netconfc:delete_config(Client, Target, infinity)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>delete_config(Client, Target, Timeout) -> Result</name> + <name name="delete_config" arity="2" since="OTP R15B02"/> + <name name="delete_config" arity="3" since="OTP R15B02"/> <fsummary>Deletes configuration data.</fsummary> - <type> - <v>Client = client()</v> - <v>Target = startup | candidate</v> - <v>Timeout = timeout()</v> - <v>Result = ok | {error, error_reason()}</v> - </type> - <desc><marker id="delete_config-3"/> + <desc> <p>Deletes configuration data.</p> <p>The running configuration cannot be deleted and <c>:candidate</c> @@ -484,54 +501,25 @@ </desc> </func> - <func> - <name>edit_config(Client, Target, Config) -> Result</name> - <fsummary>Equivalent to edit_config(Client, Target, Config, [], - infinity).</fsummary> - <desc><marker id="edit_config-3"/> - <p>Equivalent to - <seealso marker="#edit_config-5"><c>ct_netconfc:edit_config(Client, - Target, Config, [], infinity)</c></seealso>.</p> - </desc> - </func> + <func> + <name name="disconnect" arity="1" since="OTP 20.0"/> + <fsummary>Closes the given SSH connection.</fsummary> + <desc> + <p>Closes the given SSH connection.</p> - <func> - <name>edit_config(Client, Target, Config, OptParamsOrTimeout) -> Result</name> - <fsummary>If OptParamsOrTimeout is a time-out value, this function is - equivalent to ct_netconfc:edit_config(Client, Target, Config, [], - Timeout).</fsummary> - <type> - <v>Client = client()</v> - <v>Target = netconf_db()</v> - <v>Config = simple_xml()</v> - <v>OptParamsOrTimeout = [simple_xml()] | timeout()</v> - <v>Result = ok | {error, error_reason()}</v> - </type> - <desc><marker id="edit_config-4"/> - <p>If <c>OptParamsOrTimeout</c> is a time-out value, this function is - equivalent to - <seealso marker="#edit_config-5"><c>ct_netconfc:edit_config(Client, - Target, Config, [], Timeout)</c></seealso>.</p> - - <p>If <c>OptParamsOrTimeout</c> is a list of simple XML, this - function is equivalent to - <seealso marker="#edit_config-5"><c>ct_netconfc:edit_config(Client, - Target, Config, OptParams, infinity)</c></seealso>.</p> + <p>If there are open NETCONF sessions on the connection, these + will be brutally aborted. To avoid this, close each session + with <seealso marker="#close_session-1"><c>close_session/1,2</c></seealso></p> </desc> </func> <func> - <name>edit_config(Client, Target, Config, OptParams, Timeout) -> Result</name> + <name name="edit_config" arity="3" since="OTP R15B02"/> + <name name="edit_config" arity="4" clause_i="1" since="OTP 18.0"/> + <name name="edit_config" arity="4" clause_i="2" since="OTP R15B02"/> + <name name="edit_config" arity="5" since="OTP 18.0"/> <fsummary>Edits configuration data.</fsummary> - <type> - <v>Client = client()</v> - <v>Target = netconf_db()</v> - <v>Config = simple_xml()</v> - <v>OptParams = [simple_xml()]</v> - <v>Timeout = timeout()</v> - <v>Result = ok | {error, error_reason()}</v> - </type> - <desc><marker id="edit_config-5"/> + <desc> <p>Edits configuration data.</p> <p>By default only the running target is available, unless the server @@ -547,29 +535,17 @@ <pre> [{'default-operation', ["none"]}, {'error-option', ["rollback-on-error"]}]</pre> - </desc> - </func> - <func> - <name>get(Client, Filter) -> Result</name> - <fsummary>Equivalent to get(Client, Filter, infinity).</fsummary> - <desc><marker id="get-2"/> - <p>Equivalent to - <seealso marker="#get-3"><c>ct_netconfc:get(Client, Filter, - infinity)</c></seealso>.</p> + <p>If <c><anno>OptParams</anno></c> is not given, the default + value <c>[]</c> is used.</p> </desc> </func> <func> - <name>get(Client, Filter, Timeout) -> Result</name> + <name name="get" arity="2" since="OTP R15B02"/> + <name name="get" arity="3" since="OTP R15B02"/> <fsummary>Gets data.</fsummary> - <type> - <v>Client = client()</v> - <v>Filter = simple_xml() | xpath()</v> - <v>Timeout = timeout()</v> - <v>Result = {ok, [simple_xml()]} | {error, error_reason()}</v> - </type> - <desc><marker id="get-3"/> + <desc> <p>Gets data.</p> <p>This operation returns both configuration and state data from the @@ -581,24 +557,10 @@ </func> <func> - <name>get_capabilities(Client) -> Result</name> - <fsummary>Equivalent to get_capabilities(Client, infinity).</fsummary> - <desc><marker id="get_capabilities-1"/> - <p>Equivalent to - <seealso marker="#get_capabilities-2"><c>ct_netconfc:get_capabilities(Client, - infinity)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>get_capabilities(Client, Timeout) -> Result</name> + <name name="get_capabilities" arity="1" since="OTP R15B02"/> + <name name="get_capabilities" arity="2" since="OTP R15B02"/> <fsummary>Returns the server side capabilities.</fsummary> - <type> - <v>Client = client()</v> - <v>Timeout = timeout()</v> - <v>Result = [string()] | {error, error_reason()}</v> - </type> - <desc><marker id="get_capabilities-2"/> + <desc> <p>Returns the server side capabilities.</p> <p>The following capability identifiers, defined in RFC 4741 NETCONF @@ -620,26 +582,10 @@ </func> <func> - <name>get_config(Client, Source, Filter) -> Result</name> - <fsummary>Equivalent to get_config(Client, Source, Filter, - infinity).</fsummary> - <desc><marker id="get_config-3"/> - <p>Equivalent to - <seealso marker="#get_config-4"><c>ct_netconfc:get_config(Client, Source, Filter, infinity)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>get_config(Client, Source, Filter, Timeout) -> Result</name> + <name name="get_config" arity="3" since="OTP R15B02"/> + <name name="get_config" arity="4" since="OTP R15B02"/> <fsummary>Gets configuration data.</fsummary> - <type> - <v>Client = client()</v> - <v>Source = netconf_db()</v> - <v>Filter = simple_xml() | xpath()</v> - <v>Timeout = timeout()</v> - <v>Result = {ok, [simple_xml()]} | {error, error_reason()}</v> - </type> - <desc><marker id="get_config-4"/> + <desc> <p>Gets configuration data.</p> <p>To be able to access another source than <c>running</c>, the @@ -651,25 +597,12 @@ </func> <func> - <name>get_event_streams(Client, Timeout) -> Result</name> - <fsummary>Equivalent to get_event_streams(Client, [], Timeout).</fsummary> - <desc><marker id="get_event_streams-2"/> - <p>Equivalent to - <seealso marker="#get_event_streams-3"><c>ct_netconfc:get_event_streams(Client, - [], Timeout)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>get_event_streams(Client, Streams, Timeout) -> Result</name> + <name name="get_event_streams" arity="1" since="OTP 20.0"/> + <name name="get_event_streams" arity="2" clause_i="1" since="OTP R15B02"/> + <name name="get_event_streams" arity="2" clause_i="2" since="OTP 20.0"/> + <name name="get_event_streams" arity="3" since="OTP R15B02"/> <fsummary>Sends a request to get the specified event streams.</fsummary> - <type> - <v>Client = client()</v> - <v>Streams = [stream_name()]</v> - <v>Timeout = timeout()</v> - <v>Result = {ok, streams()} | {error, error_reason()}</v> - </type> - <desc><marker id="get_event_streams-3"/> + <desc> <p>Sends a request to get the specified event streams.</p> <p><c>Streams</c> is a list of stream names. The following filter is @@ -697,67 +630,28 @@ </netconf></pre> <p>If more complex filtering is needed, use - <seealso marker="#get-2"><c>ct_netconfc:get/2</c></seealso> or - <seealso marker="#get-3"><c>ct_netconfc:get/3</c></seealso> and + <seealso marker="#get-2"><c>ct_netconfc:get/2,3</c></seealso> and specify the exact filter according to "XML Schema for Event Notifications" in RFC 5277.</p> </desc> </func> <func> - <name>get_session_id(Client) -> Result</name> - <fsummary>Equivalent to get_session_id(Client, infinity).</fsummary> - <desc><marker id="get_session_id-1"/> - <p>Equivalent to - <seealso marker="#get_session_id-2"><c>ct_netconfc:get_session_id(Client, - infinity)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>get_session_id(Client, Timeout) -> Result</name> + <name name="get_session_id" arity="1" since="OTP R15B02"/> + <name name="get_session_id" arity="2" since="OTP R15B02"/> <fsummary>Returns the session Id associated with the specified client.</fsummary> - <type> - <v>Client = client()</v> - <v>Timeout = timeout()</v> - <v>Result = pos_integer() | {error, error_reason()}</v> - </type> - <desc><marker id="get_session_id-2"/> + <desc> <p>Returns the session Id associated with the specified client.</p> </desc> </func> <func> - <name>hello(Client) -> Result</name> - <fsummary>Equivalent to hello(Client, [], infinity).</fsummary> - <desc><marker id="hello-1"/> - <p>Equivalent to - <seealso marker="#hello-3"><c>ct_netconfc:hello(Client, [], - infinity)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>hello(Client, Timeout) -> Result</name> - <fsummary>Equivalent to hello(Client, [], Timeout).</fsummary> - <desc><marker id="hello-2"/> - <p>Equivalent to - <seealso marker="#hello-3"><c>ct_netconfc:hello(Client, [], - Timeout)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>hello(Client, Options, Timeout) -> Result</name> + <name name="hello" arity="1" since="OTP R15B02"/> + <name name="hello" arity="2" since="OTP R15B02"/> + <name name="hello" arity="3" since="OTP 17.5.3"/> <fsummary>Exchanges hello messages with the server.</fsummary> - <type> - <v>Client = handle()</v> - <v>Options = [{capability, [string()]}]</v> - <v>Timeout = timeout()</v> - <v>Result = ok | {error, error_reason()}</v> - </type> - <desc><marker id="hello-3"/> + <desc> <p>Exchanges <c>hello</c> messages with the server.</p> <p>Adds optional capabilities and sends a <c>hello</c> message to the @@ -766,27 +660,11 @@ </func> <func> - <name>kill_session(Client, SessionId) -> Result</name> - <fsummary>Equivalent to kill_session(Client, SessionId, - infinity).</fsummary> - <desc><marker id="kill_session-2"/> - <p>Equivalent to - <seealso marker="#kill_session-3"><c>ct_netconfc:kill_session(Client, -SessionId, infinity)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>kill_session(Client, SessionId, Timeout) -> Result</name> + <name name="kill_session" arity="2" since="OTP R15B02"/> + <name name="kill_session" arity="3" since="OTP R15B02"/> <fsummary>Forces termination of the session associated with the supplied session Id.</fsummary> - <type> - <v>Client = client()</v> - <v>SessionId = pos_integer()</v> - <v>Timeout = timeout()</v> - <v>Result = ok | {error, error_reason()}</v> - </type> - <desc><marker id="kill_session-3"/> + <desc> <p>Forces termination of the session associated with the supplied session Id.</p> @@ -804,26 +682,11 @@ SessionId, infinity)</c></seealso>.</p> </func> <func> - <name>lock(Client, Target) -> Result</name> - <fsummary>Equivalent to lock(Client, Target, infinity).</fsummary> - <desc><marker id="lock-2"/> - <p>Equivalent to - <seealso marker="#lock-3"><c>ct_netconfc:lock(Client, Target, - infinity)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>lock(Client, Target, Timeout) -> Result</name> - <fsummary>Unlocks the configuration target.</fsummary> - <type> - <v>Client = client()</v> - <v>Target = netconf_db()</v> - <v>Timeout = timeout()</v> - <v>Result = ok | {error, error_reason()}</v> - </type> - <desc><marker id="lock-3"/> - <p>Unlocks the configuration target.</p> + <name name="lock" arity="2" since="OTP R15B02"/> + <name name="lock" arity="3" since="OTP R15B02"/> + <fsummary>Locks the configuration target.</fsummary> + <desc> + <p>Locks the configuration target.</p> <p>Which target parameters that can be used depends on if <c>:candidate</c> and/or <c>:startup</c> are supported by the @@ -832,9 +695,7 @@ SessionId, infinity)</c></seealso>.</p> Locks are intended to be short-lived.</p> <p>Operation - <seealso marker="#kill_session-2"><c>ct_netconfc:kill_session/2</c></seealso> - or - <seealso marker="#kill_session-3"><c>ct_netconfc:kill_session/3</c></seealso> + <seealso marker="#kill_session-2"><c>kill_session/2,3</c></seealso> can be used to force the release of a lock owned by another NETCONF session. How this is achieved by the server side is implementation-specific.</p> @@ -842,54 +703,41 @@ SessionId, infinity)</c></seealso>.</p> </func> <func> - <name>only_open(Options) -> Result</name> + <name name="only_open" arity="1" since="OTP R15B02"/> <fsummary>Opens a NETCONF session, but does not send hello.</fsummary> - <type> - <v>Options = options()</v> - <v>Result = {ok, handle()} | {error, error_reason()}</v> - </type> - <desc><marker id="only_open-1"/> + <desc> <p>Opens a NETCONF session, but does not send <c>hello</c>.</p> - <p>As <seealso marker="#open-1"><c>ct_netconfc:open/1</c></seealso>, - but does not send a <c>hello</c> message.</p> + <p>As <seealso marker="#open-1"><c>open/1</c></seealso>, but + does not send a <c>hello</c> message.</p> </desc> </func> <func> - <name>only_open(KeyOrName, ExtraOptions) -> Result</name> - <fsummary>Opens a name NETCONF session, but does not send - hello.</fsummary> - <type> - <v>KeyOrName = key_or_name()</v> - <v>ExtraOptions = options()</v> - <v>Result = {ok, handle()} | {error, error_reason()}</v> - </type> - <desc><marker id="only_open-2"/> - <p>Opens a name NETCONF session, but does not send <c>hello</c>.</p> - - <p>As <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>, - but does not send a <c>hello</c> message.</p> + <name name="only_open" arity="2" since="OTP R15B02"/> + <fsummary>Opens a named NETCONF session, but does not send hello.</fsummary> + <desc> + <p>Opens a named NETCONF session, but does not send <c>hello</c>.</p> + + <p>As <seealso marker="#open-2"><c>open/2</c></seealso>, but + does not send a <c>hello</c> message.</p> </desc> </func> <func> - <name>open(Options) -> Result</name> - <fsummary>Opens a NETCONF session and exchanges hello messages.</fsummary> - <type> - <v>Options = options()</v> - <v>Result = {ok, handle()} | {error, error_reason()}</v> - </type> - <desc><marker id="open-1"/> + <name name="open" arity="1" since="OTP R15B02"/> + <fsummary>Opens a NETCONF session and exchanges hello messages.</fsummary> + <desc> <p>Opens a NETCONF session and exchanges <c>hello</c> messages.</p> <p>If the server options are specified in a configuration file, or if a named client is needed for logging purposes (see section <seealso marker="#Logging">Logging</seealso> in this module), use - <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso> + <seealso marker="#open-2"><c>open/2</c></seealso> instead.</p> - <p>The opaque <c>handle()</c> reference returned from this + <p>The opaque <seealso marker="#type-handle"><c>handle()</c></seealso> + reference returned from this function is required as client identifier when calling any other function in this module.</p> @@ -901,37 +749,36 @@ SessionId, infinity)</c></seealso>.</p> </func> <func> - <name>open(KeyOrName, ExtraOptions) -> Result</name> + <name name="open" arity="2" since="OTP R15B02"/> <fsummary>Opens a named NETCONF session and exchanges hello messages.</fsummary> - <type> - <v>KeyOrName = key_or_name()</v> - <v>ExtraOptions = options()</v> - <v>Result = {ok, handle()} | {error, error_reason()}</v> - </type> - <desc><marker id="open-2"/> + <desc> <p>Opens a named NETCONF session and exchanges <c>hello</c> messages.</p> - <p>If <c>KeyOrName</c> is a configured <c>server_id()</c> or a + <p>If <c><anno>KeyOrName</anno></c> is a + configured <c>server_id()</c> or a <c>target_name()</c> associated with such an Id, then the options for this server are fetched from the configuration file.</p> - <p>Argument <c>ExtraOptions</c> is added to the options found in the - configuration file. If the same options are specified, the values - from the configuration file overwrite <c>ExtraOptions</c>.</p> + <p>Argument <c><anno>ExtraOptions</anno></c> is added to the + options found in the configuration file. If the same + options are specified, the values from the configuration + file overwrite <c><anno>ExtraOptions</anno></c>.</p> <p>If the server is not specified in a configuration file, use - <seealso marker="#open-1"><c>ct_netconfc:open/1</c></seealso> + <seealso marker="#open-1"><c>open/1</c></seealso> instead.</p> - <p>The opaque <c>handle()</c> reference returned from this + <p>The opaque <seealso marker="#type-handle"><c>handle()</c></seealso> + reference returned from this function can be used as client identifier when calling any other - function in this module. However, if <c>KeyOrName</c> is a + function in this module. However, if <c><anno>KeyOrName</anno></c> is a <c>target_name()</c>, that is, if the server is named through a call to <seealso marker="ct#require-2"><c>ct:require/2</c></seealso> or a <c>require</c> statement in the test suite, then this name can - be used instead of <c>handle()</c>.</p> + be used instead of + <seealso marker="#type-handle"><c>handle()</c></seealso>.</p> <p>Option <c>timeout</c> (milliseconds) is used when setting up the SSH connection and when waiting for the <c>hello</c> message from @@ -944,25 +791,10 @@ SessionId, infinity)</c></seealso>.</p> </func> <func> - <name>send(Client, SimpleXml) -> Result</name> - <fsummary>Equivalent to send(Client, SimpleXml, infinity).</fsummary> - <desc><marker id="send-2"/> - <p>Equivalent to - <seealso marker="#send-3"><c>ct_netconfc:send(Client, SimpleXml, - infinity)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>send(Client, SimpleXml, Timeout) -> Result</name> + <name name="send" arity="2" since="OTP R16B02"/> + <name name="send" arity="3" since="OTP R16B02"/> <fsummary>Sends an XML document to the server.</fsummary> - <type> - <v>Client = client()</v> - <v>SimpleXml = simple_xml()</v> - <v>Timeout = timeout()</v> - <v>Result = simple_xml() | {error, error_reason()}</v> - </type> - <desc><marker id="send-3"/> + <desc> <p>Sends an XML document to the server.</p> <p>The specified XML document is sent "as is" to the server. This @@ -972,25 +804,10 @@ SessionId, infinity)</c></seealso>.</p> </func> <func> - <name>send_rpc(Client, SimpleXml) -> Result</name> - <fsummary>Equivalent to send_rpc(Client, SimpleXml, infinity).</fsummary> - <desc><marker id="send_rpc-2"/> - <p>Equivalent to - <seealso marker="#send_rpc-3"><c>ct_netconfc:send_rpc(Client, - SimpleXml, infinity)</c></seealso>.</p> - </desc> - </func> - - <func> - <name>send_rpc(Client, SimpleXml, Timeout) -> Result</name> + <name name="send_rpc" arity="2" since="OTP R16B02"/> + <name name="send_rpc" arity="3" since="OTP R16B02"/> <fsummary>Sends a NETCONF rpc request to the server.</fsummary> - <type> - <v>Client = client()</v> - <v>SimpleXml = simple_xml()</v> - <v>Timeout = timeout()</v> - <v>Result = [simple_xml()] | {error, error_reason()}</v> - </type> - <desc><marker id="send_rpc-3"/> + <desc> <p>Sends a NETCONF <c>rpc</c> request to the server.</p> <p>The specified XML document is wrapped in a valid NETCONF <c>rpc</c> @@ -1003,30 +820,42 @@ SessionId, infinity)</c></seealso>.</p> </func> <func> - <name>unlock(Client, Target) -> Result</name> - <fsummary>Equivalent to unlock(Client, Target, infinity).</fsummary> - <desc><marker id="unlock-2"/> - <p>Equivalent to - <seealso marker="#unlock-3"><c>ct_netconfc:unlock(Client, Target, - infinity)</c></seealso>.</p> + <name name="session" arity="1" since="OTP 20.0"/> + <name name="session" arity="2" clause_i="1" since="OTP 20.0"/> + <name name="session" arity="2" clause_i="2" since="OTP 20.0"/> + <name name="session" arity="3" since="OTP 20.0"/> + <fsummary>Opens a NETCONF session as a channel on the given SSH + connection, and exchanges hello messages with the + server.</fsummary> + <type name="session_options"/> + <type name="session_option"/> + <desc> + <p>Opens a NETCONF session as a channel on the given SSH + connection, and exchanges hello messages with the server.</p> + + <p>The opaque <seealso marker="#type-handle"><c>handle()</c></seealso> + reference returned from this + function can be used as client identifier when calling any + other function in this module. However, if <c><anno>KeyOrName</anno></c> + is used and it is a <c>target_name()</c>, that is, if the + server is named through a call + to <seealso marker="ct#require-2"><c>ct:require/2</c></seealso> + or a <c>require</c> statement in the test suite, then this + name can be used instead of + <seealso marker="#type-handle"><c>handle()</c></seealso>.</p> + </desc> </func> <func> - <name>unlock(Client, Target, Timeout) -> Result</name> + <name name="unlock" arity="2" since="OTP R15B02"/> + <name name="unlock" arity="3" since="OTP R15B02"/> <fsummary>Unlocks the configuration target.</fsummary> - <type> - <v>Client = client()</v> - <v>Target = netconf_db()</v> - <v>Timeout = timeout()</v> - <v>Result = ok | {error, error_reason()}</v> - </type> - <desc><marker id="unlock-3"/> + <desc> <p>Unlocks the configuration target.</p> <p>If the client earlier has acquired a lock through - <seealso marker="#lock-2"><c>ct_netconfc:lock/2</c></seealso> or - <seealso marker="#lock-3"><c>ct_netconfc:lock/3</c></seealso>, this + <seealso marker="#lock-2"><c>lock/2,3</c></seealso>, this operation releases the associated lock. To access another target than <c>running</c>, the server must support <c>:candidate</c> and/or <c>:startup</c>.</p> diff --git a/lib/common_test/doc/src/ct_property_test.xml b/lib/common_test/doc/src/ct_property_test.xml index 2e9bd1969c..1e01d9a5d7 100644 --- a/lib/common_test/doc/src/ct_property_test.xml +++ b/lib/common_test/doc/src/ct_property_test.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>ct_property_test.xml</file> </header> - <module>ct_property_test</module> + <module since="OTP 17.3">ct_property_test</module> <modulesummary>EXPERIMENTAL support in Common Test for calling property-based tests.</modulesummary> @@ -79,7 +79,7 @@ <funcs> <func> - <name>init_per_suite(Config) -> Config | {skip, Reason}</name> + <name since="OTP 17.3">init_per_suite(Config) -> Config | {skip, Reason}</name> <fsummary>Initializes Config for property testing.</fsummary> <desc><marker id="init_per_suite-1"/> <p>Initializes <c>Config</c> for property testing.</p> @@ -98,7 +98,7 @@ </func> <func> - <name>quickcheck(Property, Config) -> true | {fail, Reason}</name> + <name since="OTP 17.3">quickcheck(Property, Config) -> true | {fail, Reason}</name> <fsummary>Calls quickcheck and returns the result in a form suitable for Common Test.</fsummary> <desc><marker id="quickcheck-2"/> diff --git a/lib/common_test/doc/src/ct_rpc.xml b/lib/common_test/doc/src/ct_rpc.xml index 0169727581..00a4dcec08 100644 --- a/lib/common_test/doc/src/ct_rpc.xml +++ b/lib/common_test/doc/src/ct_rpc.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>ct_rpc.xml</file> </header> - <module>ct_rpc</module> + <module since="">ct_rpc</module> <modulesummary>Common Test specific layer on Erlang/OTP rpc.</modulesummary> <description> @@ -43,7 +43,7 @@ <funcs> <func> - <name>app_node(App, Candidates) -> NodeName</name> + <name since="">app_node(App, Candidates) -> NodeName</name> <fsummary>From a set of candidate nodes determines which of them is running the application App.</fsummary> <type> @@ -61,7 +61,7 @@ </func> <func> - <name>app_node(App, Candidates, FailOnBadRPC) -> NodeName</name> + <name since="">app_node(App, Candidates, FailOnBadRPC) -> NodeName</name> <fsummary>Same as app_node/2, except that argument FailOnBadRPC determines if the search for a candidate node is to stop if badrpc is received at some point.</fsummary> @@ -81,7 +81,7 @@ </func> <func> - <name>app_node(App, Candidates, FailOnBadRPC, Cookie) -> NodeName</name> + <name since="">app_node(App, Candidates, FailOnBadRPC, Cookie) -> NodeName</name> <fsummary>Same as app_node/2, except that argument FailOnBadRPC determines if the search for a candidate node is to stop if badrpc is received at some point.</fsummary> @@ -105,7 +105,7 @@ </func> <func> - <name>call(Node, Module, Function, Args) -> term() | {badrpc, Reason}</name> + <name since="">call(Node, Module, Function, Args) -> term() | {badrpc, Reason}</name> <fsummary>Same as call(Node, Module, Function, Args, infinity).</fsummary> <desc><marker id="call-4"/> <p>Same as <c>call(Node, Module, Function, Args, infinity)</c>.</p> @@ -113,7 +113,7 @@ </func> <func> - <name>call(Node, Module, Function, Args, TimeOut) -> term() | {badrpc, Reason}</name> + <name since="">call(Node, Module, Function, Args, TimeOut) -> term() | {badrpc, Reason}</name> <fsummary>Evaluates apply(Module, Function, Args) on the node Node.</fsummary> <type> @@ -136,7 +136,7 @@ </func> <func> - <name>call(Node, Module, Function, Args, TimeOut, Cookie) -> term() | {badrpc, Reason}</name> + <name since="">call(Node, Module, Function, Args, TimeOut, Cookie) -> term() | {badrpc, Reason}</name> <fsummary>Evaluates apply(Module, Function, Args) on the node Node.</fsummary> <type> @@ -163,7 +163,7 @@ </func> <func> - <name>cast(Node, Module, Function, Args) -> ok</name> + <name since="">cast(Node, Module, Function, Args) -> ok</name> <fsummary>Evaluates apply(Module, Function, Args) on the node Node.</fsummary> <type> @@ -187,7 +187,7 @@ </func> <func> - <name>cast(Node, Module, Function, Args, Cookie) -> ok</name> + <name since="">cast(Node, Module, Function, Args, Cookie) -> ok</name> <fsummary>Evaluates apply(Module, Function, Args) on the node Node.</fsummary> <type> diff --git a/lib/common_test/doc/src/ct_run.xml b/lib/common_test/doc/src/ct_run.xml index 2552938346..5b962ed5c7 100644 --- a/lib/common_test/doc/src/ct_run.xml +++ b/lib/common_test/doc/src/ct_run.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>2007</year><year>2013</year> + <year>2007</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -125,6 +125,7 @@ [-until [YYMoMoDD]HHMMSS [-force_stop [skip_rest]]] [-basic_html] [-no_esc_chars] + [-keep_logs all | NLogs] [-ct_hooks CTHModule1 CTHOpts1 and CTHModule2 CTHOpts2 and .. CTHModuleN CTHOptsN] [-exit_status ignore_config] @@ -164,6 +165,7 @@ [-until [YYMoMoDD]HHMMSS [-force_stop [skip_rest]]] [-basic_html] [-no_esc_chars] + [-keep_logs all | NLogs] [-ct_hooks CTHModule1 CTHOpts1 and CTHModule2 CTHOpts2 and .. CTHModuleN CTHOptsN] [-exit_status ignore_config]</pre> @@ -189,13 +191,15 @@ [-scale_timetraps] [-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc] [-basic_html] - [-no_esc_chars]</pre> + [-no_esc_chars] + [-keep_logs all | NLogs]</pre> </section> <section> <title>Refresh HTML Index Files</title> <pre> - ct_run -refresh_logs [-logdir LogDir] [-basic_html]</pre> + ct_run -refresh_logs [-logdir LogDir] [-basic_html] + [-keep_logs all | NLogs]</pre> </section> <section> diff --git a/lib/common_test/doc/src/ct_slave.xml b/lib/common_test/doc/src/ct_slave.xml index 44a7b7873f..84e619482d 100644 --- a/lib/common_test/doc/src/ct_slave.xml +++ b/lib/common_test/doc/src/ct_slave.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>ct_slave.xml</file> </header> - <module>ct_slave</module> + <module since="OTP R14B">ct_slave</module> <modulesummary>Common Test framework functions for starting and stopping nodes for Large-Scale Testing.</modulesummary> @@ -50,7 +50,7 @@ <funcs> <func> - <name>start(Node) -> Result</name> + <name since="OTP R14B">start(Node) -> Result</name> <fsummary>Starts an Erlang node with name Node on the local host.</fsummary> <type> @@ -68,7 +68,7 @@ </func> <func> - <name>start(HostOrNode, NodeOrOpts) -> Result</name> + <name since="OTP R14B">start(HostOrNode, NodeOrOpts) -> Result</name> <fsummary>Starts an Erlang node with default options on a specified host, or on the local host with specified options.</fsummary> <type> @@ -90,7 +90,7 @@ </func> <func> - <name>start(Host, Node, Opts) -> Result</name> + <name since="OTP R14B">start(Host, Node, Opts) -> Result</name> <fsummary>Starts an Erlang node with name Node on host Host as specified by the combination of options in Opts.</fsummary> <type> @@ -184,7 +184,7 @@ </func> <func> - <name>stop(Node) -> Result</name> + <name since="OTP R14B">stop(Node) -> Result</name> <fsummary>Stops the running Erlang node with name Node on the local host.</fsummary> <type> @@ -199,7 +199,7 @@ </func> <func> - <name>stop(Host, Node) -> Result</name> + <name since="OTP R14B">stop(Host, Node) -> Result</name> <fsummary>Stops the running Erlang node with name Node on host Host.</fsummary> <type> diff --git a/lib/common_test/doc/src/ct_snmp.xml b/lib/common_test/doc/src/ct_snmp.xml index d001fb24ec..343781814a 100644 --- a/lib/common_test/doc/src/ct_snmp.xml +++ b/lib/common_test/doc/src/ct_snmp.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>ct_snmp.xml</file> </header> - <module>ct_snmp</module> + <module since="">ct_snmp</module> <modulesummary>Common Test user interface module for the SNMP application.</modulesummary> <description> @@ -240,7 +240,7 @@ <funcs> <func> - <name>get_next_values(Agent, Oids, MgrAgentConfName) -> SnmpReply</name> + <name since="">get_next_values(Agent, Oids, MgrAgentConfName) -> SnmpReply</name> <fsummary>Issues a synchronous SNMP get next request.</fsummary> <type> <v>Agent = agent_name()</v> @@ -254,7 +254,7 @@ </func> <func> - <name>get_values(Agent, Oids, MgrAgentConfName) -> SnmpReply</name> + <name since="">get_values(Agent, Oids, MgrAgentConfName) -> SnmpReply</name> <fsummary>Issues a synchronous SNMP get request.</fsummary> <type> <v>Agent = agent_name()</v> @@ -268,7 +268,7 @@ </func> <func> - <name>load_mibs(Mibs) -> ok | {error, Reason}</name> + <name since="">load_mibs(Mibs) -> ok | {error, Reason}</name> <fsummary>Loads the MIBs into agent snmp_master_agent.</fsummary> <type> <v>Mibs = [MibName]</v> @@ -281,7 +281,7 @@ </func> <func> - <name>register_agents(MgrAgentConfName, ManagedAgents) -> ok | {error, Reason}</name> + <name since="">register_agents(MgrAgentConfName, ManagedAgents) -> ok | {error, Reason}</name> <fsummary>Explicitly instructs the manager to handle this agent.</fsummary> <type> @@ -300,7 +300,7 @@ </func> <func> - <name>register_users(MgrAgentConfName, Users) -> ok | {error, Reason}</name> + <name since="">register_users(MgrAgentConfName, Users) -> ok | {error, Reason}</name> <fsummary>Registers the manager entity (=user) responsible for specific agent(s).</fsummary> <type> @@ -319,7 +319,7 @@ </func> <func> - <name>register_usm_users(MgrAgentConfName, UsmUsers) -> ok | {error, Reason}</name> + <name since="">register_usm_users(MgrAgentConfName, UsmUsers) -> ok | {error, Reason}</name> <fsummary>Explicitly instructs the manager to handle this USM user.</fsummary> <type> <v>MgrAgentConfName = atom()</v> @@ -337,7 +337,7 @@ </func> <func> - <name>set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}]</name> + <name since="">set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}]</name> <fsummary>Returns a list of all successful set requests performed in the test case in reverse order.</fsummary> <type> @@ -357,7 +357,7 @@ </func> <func> - <name>set_values(Agent, VarsAndVals, MgrAgentConfName, Config) -> SnmpReply</name> + <name since="">set_values(Agent, VarsAndVals, MgrAgentConfName, Config) -> SnmpReply</name> <fsummary>Issues a synchronous SNMP set request.</fsummary> <type> <v>Agent = agent_name()</v> @@ -372,7 +372,7 @@ </func> <func> - <name>start(Config, MgrAgentConfName) -> ok</name> + <name since="">start(Config, MgrAgentConfName) -> ok</name> <fsummary>Equivalent to start(Config, MgrAgentConfName, undefined).</fsummary> <desc><marker id="start-2"/> @@ -383,7 +383,7 @@ </func> <func> - <name>start(Config, MgrAgentConfName, SnmpAppConfName) -> ok</name> + <name since="">start(Config, MgrAgentConfName, SnmpAppConfName) -> ok</name> <fsummary>Starts an SNMP manager and/or agent.</fsummary> <type> <v>Config = [{Key, Value}]</v> @@ -415,7 +415,7 @@ </func> <func> - <name>stop(Config) -> ok</name> + <name since="">stop(Config) -> ok</name> <fsummary>Stops the SNMP manager and/or agent, and removes all files created.</fsummary> <type> @@ -430,7 +430,7 @@ </func> <func> - <name>unload_mibs(Mibs) -> ok | {error, Reason}</name> + <name since="OTP R16B">unload_mibs(Mibs) -> ok | {error, Reason}</name> <fsummary>Unloads the MIBs from agent snmp_master_agent.</fsummary> <type> <v>Mibs = [MibName]</v> @@ -443,7 +443,7 @@ </func> <func> - <name>unregister_agents(MgrAgentConfName) -> ok</name> + <name since="">unregister_agents(MgrAgentConfName) -> ok</name> <fsummary>Unregisters all managed agents.</fsummary> <type> <v>MgrAgentConfName = atom()</v> @@ -455,7 +455,7 @@ </func> <func> - <name>unregister_agents(MgrAgentConfName, ManagedAgents) -> ok</name> + <name since="OTP R16B">unregister_agents(MgrAgentConfName, ManagedAgents) -> ok</name> <fsummary>Unregisters the specified managed agents.</fsummary> <type> <v>MgrAgentConfName = atom()</v> @@ -468,7 +468,7 @@ </func> <func> - <name>unregister_users(MgrAgentConfName) -> ok</name> + <name since="">unregister_users(MgrAgentConfName) -> ok</name> <fsummary>Unregisters all users.</fsummary> <type> <v>MgrAgentConfName = atom()</v> @@ -480,7 +480,7 @@ </func> <func> - <name>unregister_users(MgrAgentConfName, Users) -> ok</name> + <name since="OTP R16B">unregister_users(MgrAgentConfName, Users) -> ok</name> <fsummary>Unregisters the specified users.</fsummary> <type> <v>MgrAgentConfName = atom()</v> @@ -493,7 +493,7 @@ </func> <func> - <name>unregister_usm_users(MgrAgentConfName) -> ok</name> + <name since="OTP R16B">unregister_usm_users(MgrAgentConfName) -> ok</name> <fsummary>Unregisters all USM users.</fsummary> <type> <v>MgrAgentConfName = atom()</v> @@ -505,7 +505,7 @@ </func> <func> - <name>unregister_usm_users(MgrAgentConfName, UsmUsers) -> ok</name> + <name since="OTP R16B">unregister_usm_users(MgrAgentConfName, UsmUsers) -> ok</name> <fsummary>Unregisters the specified USM users.</fsummary> <type> <v>MgrAgentConfName = atom()</v> diff --git a/lib/common_test/doc/src/ct_ssh.xml b/lib/common_test/doc/src/ct_ssh.xml index 92b1f60b8c..8d9f31aff8 100644 --- a/lib/common_test/doc/src/ct_ssh.xml +++ b/lib/common_test/doc/src/ct_ssh.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>ct_ssh.xml</file> </header> - <module>ct_ssh</module> + <module since="">ct_ssh</module> <modulesummary>SSH/SFTP client module.</modulesummary> <description> @@ -64,7 +64,7 @@ <p><c>ConnType = ssh | sftp</c>.</p> <p>For other types, see - <seealso marker="ssh:ssh"><c>ssh:ssh(3)</c></seealso>.</p> + <seealso marker="ssh:ssh"><c>ssh(3)</c></seealso>.</p> <p>All time-out parameters in <c>ct_ssh</c> functions are values in milliseconds.</p> @@ -88,14 +88,14 @@ <tag><c>ssh_sftp_return() = term()</c></tag> <item><marker id="type-ssh_sftp_return"/> <p>Return value from an - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp</c></seealso> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp</c></seealso> function.</p></item> </taglist> </section> <funcs> <func> - <name>apread(SSH, Handle, Position, Length) -> Result</name> + <name since="">apread(SSH, Handle, Position, Length) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -104,12 +104,12 @@ </type> <desc><marker id="apread-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>apread(SSH, Server, Handle, Position, Length) -> Result</name> + <name since="">apread(SSH, Server, Handle, Position, Length) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -118,12 +118,12 @@ </type> <desc><marker id="apread-5"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>apwrite(SSH, Handle, Position, Data) -> Result</name> + <name since="">apwrite(SSH, Handle, Position, Data) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -132,12 +132,12 @@ </type> <desc><marker id="apwrite-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>apwrite(SSH, Server, Handle, Position, Data) -> Result</name> + <name since="">apwrite(SSH, Server, Handle, Position, Data) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -146,12 +146,12 @@ </type> <desc><marker id="apwrite-5"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>aread(SSH, Handle, Len) -> Result</name> + <name since="">aread(SSH, Handle, Len) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -160,12 +160,12 @@ </type> <desc><marker id="aread-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>aread(SSH, Server, Handle, Len) -> Result</name> + <name since="">aread(SSH, Server, Handle, Len) -> Result</name> <fsummary>For inforamtion and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -174,12 +174,12 @@ </type> <desc><marker id="aread-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>awrite(SSH, Handle, Data) -> Result</name> + <name since="">awrite(SSH, Handle, Data) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -188,12 +188,12 @@ </type> <desc><marker id="awrite-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>awrite(SSH, Server, Handle, Data) -> Result</name> + <name since="">awrite(SSH, Server, Handle, Data) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -202,12 +202,12 @@ </type> <desc><marker id="awrite-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>close(SSH, Handle) -> Result</name> + <name since="">close(SSH, Handle) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -216,12 +216,12 @@ </type> <desc><marker id="close-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>close(SSH, Server, Handle) -> Result</name> + <name since="">close(SSH, Server, Handle) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -230,12 +230,12 @@ </type> <desc><marker id="close-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>connect(KeyOrName) -> {ok, Handle} | {error, Reason}</name> + <name since="">connect(KeyOrName) -> {ok, Handle} | {error, Reason}</name> <fsummary>Equivalent to connect(KeyOrName, host, []).</fsummary> <desc><marker id="connect-1"/> <p>Equivalent to @@ -245,7 +245,7 @@ </func> <func> - <name>connect(KeyOrName, ConnType) -> {ok, Handle} | {error, Reason}</name> + <name since="">connect(KeyOrName, ConnType) -> {ok, Handle} | {error, Reason}</name> <fsummary>Equivalent to connect(KeyOrName, ConnType, []).</fsummary> <desc><marker id="connect-2"/> <p>Equivalent to @@ -255,7 +255,7 @@ </func> <func> - <name>connect(KeyOrName, ConnType, ExtraOpts) -> {ok, Handle} | {error, Reason}</name> + <name since="">connect(KeyOrName, ConnType, ExtraOpts) -> {ok, Handle} | {error, Reason}</name> <fsummary>Opens an SSH or SFTP connection using the information associated with KeyOrName.</fsummary> <type> @@ -301,7 +301,7 @@ </func> <func> - <name>del_dir(SSH, Name) -> Result</name> + <name since="">del_dir(SSH, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -310,12 +310,12 @@ </type> <desc><marker id="del_dir-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>del_dir(SSH, Server, Name) -> Result</name> + <name since="">del_dir(SSH, Server, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -324,12 +324,12 @@ </type> <desc><marker id="del_dir-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>delete(SSH, Name) -> Result</name> + <name since="">delete(SSH, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -338,12 +338,12 @@ </type> <desc><marker id="delete-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>delete(SSH, Server, Name) -> Result</name> + <name since="">delete(SSH, Server, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -352,12 +352,12 @@ </type> <desc><marker id="delete-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>disconnect(SSH) -> ok | {error, Reason}</name> + <name since="">disconnect(SSH) -> ok | {error, Reason}</name> <fsummary>Closes an SSH/SFTP connection.</fsummary> <type> <v>SSH = connection()</v> @@ -369,7 +369,7 @@ </func> <func> - <name>exec(SSH, Command) -> {ok, Data} | {error, Reason}</name> + <name since="">exec(SSH, Command) -> {ok, Data} | {error, Reason}</name> <fsummary>Equivalent to exec(SSH, Command, DefaultTimeout).</fsummary> <desc><marker id="exec-2"/> <p>Equivalent to @@ -379,7 +379,7 @@ </func> <func> - <name>exec(SSH, Command, Timeout) -> {ok, Data} | {error, Reason}</name> + <name since="">exec(SSH, Command, Timeout) -> {ok, Data} | {error, Reason}</name> <fsummary>Requests server to perform Command.</fsummary> <type> <v>SSH = connection()</v> @@ -396,7 +396,7 @@ </func> <func> - <name>exec(SSH, ChannelId, Command, Timeout) -> {ok, Data} | {error, Reason}</name> + <name since="">exec(SSH, ChannelId, Command, Timeout) -> {ok, Data} | {error, Reason}</name> <fsummary>Requests server to perform Command.</fsummary> <type> <v>SSH = connection()</v> @@ -414,7 +414,7 @@ </func> <func> - <name>get_file_info(SSH, Handle) -> Result</name> + <name since="">get_file_info(SSH, Handle) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -423,12 +423,12 @@ </type> <desc><marker id="get_file_info-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>get_file_info(SSH, Server, Handle) -> Result</name> + <name since="">get_file_info(SSH, Server, Handle) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -437,12 +437,12 @@ </type> <desc><marker id="get_file_info-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>list_dir(SSH, Path) -> Result</name> + <name since="">list_dir(SSH, Path) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -451,12 +451,12 @@ </type> <desc><marker id="list_dir-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>list_dir(SSH, Server, Path) -> Result</name> + <name since="">list_dir(SSH, Server, Path) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -465,12 +465,12 @@ </type> <desc><marker id="list_dir-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>make_dir(SSH, Name) -> Result</name> + <name since="">make_dir(SSH, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -479,12 +479,12 @@ </type> <desc><marker id="make_dir-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>make_dir(SSH, Server, Name) -> Result</name> + <name since="">make_dir(SSH, Server, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -493,12 +493,12 @@ </type> <desc><marker id="make_dir-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>make_symlink(SSH, Name, Target) -> Result</name> + <name since="">make_symlink(SSH, Name, Target) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -507,12 +507,12 @@ </type> <desc><marker id="make_symlink-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>make_symlink(SSH, Server, Name, Target) -> Result</name> + <name since="">make_symlink(SSH, Server, Name, Target) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -521,12 +521,12 @@ </type> <desc><marker id="make_symlink-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>open(SSH, File, Mode) -> Result</name> + <name since="">open(SSH, File, Mode) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -535,12 +535,12 @@ </type> <desc><marker id="open-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>open(SSH, Server, File, Mode) -> Result</name> + <name since="">open(SSH, Server, File, Mode) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -549,12 +549,12 @@ </type> <desc><marker id="open-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>opendir(SSH, Path) -> Result</name> + <name since="">opendir(SSH, Path) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -563,12 +563,12 @@ </type> <desc><marker id="opendir-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>opendir(SSH, Server, Path) -> Result</name> + <name since="">opendir(SSH, Server, Path) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -577,12 +577,12 @@ </type> <desc><marker id="opendir-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>position(SSH, Handle, Location) -> Result</name> + <name since="">position(SSH, Handle, Location) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -591,12 +591,12 @@ </type> <desc><marker id="position-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>position(SSH, Server, Handle, Location) -> Result</name> + <name since="">position(SSH, Server, Handle, Location) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -605,12 +605,12 @@ </type> <desc><marker id="position-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>pread(SSH, Handle, Position, Length) -> Result</name> + <name since="">pread(SSH, Handle, Position, Length) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -619,12 +619,12 @@ </type> <desc><marker id="pread-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>pread(SSH, Server, Handle, Position, Length) -> Result</name> + <name since="">pread(SSH, Server, Handle, Position, Length) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -633,12 +633,12 @@ </type> <desc><marker id="pread-5"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>pwrite(SSH, Handle, Position, Data) -> Result</name> + <name since="">pwrite(SSH, Handle, Position, Data) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -647,12 +647,12 @@ </type> <desc><marker id="pwrite-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>pwrite(SSH, Server, Handle, Position, Data) -> Result</name> + <name since="">pwrite(SSH, Server, Handle, Position, Data) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -661,12 +661,12 @@ </type> <desc><marker id="pwrite-5"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>read(SSH, Handle, Len) -> Result</name> + <name since="">read(SSH, Handle, Len) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -675,12 +675,12 @@ </type> <desc><marker id="read-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>read(SSH, Server, Handle, Len) -> Result</name> + <name since="">read(SSH, Server, Handle, Len) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -689,12 +689,12 @@ </type> <desc><marker id="read-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>read_file(SSH, File) -> Result</name> + <name since="">read_file(SSH, File) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -703,12 +703,12 @@ </type> <desc><marker id="read_file-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>read_file(SSH, Server, File) -> Result</name> + <name since="">read_file(SSH, Server, File) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -717,12 +717,12 @@ </type> <desc><marker id="read_file-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>read_file_info(SSH, Name) -> Result</name> + <name since="">read_file_info(SSH, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -731,12 +731,12 @@ </type> <desc><marker id="read_file_info-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>read_file_info(SSH, Server, Name) -> Result</name> + <name since="">read_file_info(SSH, Server, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -745,12 +745,12 @@ </type> <desc><marker id="read_file_info-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>read_link(SSH, Name) -> Result</name> + <name since="">read_link(SSH, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -759,12 +759,12 @@ </type> <desc><marker id="read_link-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>read_link(SSH, Server, Name) -> Result</name> + <name since="">read_link(SSH, Server, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -773,12 +773,12 @@ </type> <desc><marker id="read_link-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>read_link_info(SSH, Name) -> Result</name> + <name since="">read_link_info(SSH, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -787,12 +787,12 @@ </type> <desc><marker id="read_link_info-2"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>read_link_info(SSH, Server, Name) -> Result</name> + <name since="">read_link_info(SSH, Server, Name) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -801,12 +801,12 @@ </type> <desc><marker id="read_link_info-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>receive_response(SSH, ChannelId) -> {ok, Data} | {error, Reason}</name> + <name since="">receive_response(SSH, ChannelId) -> {ok, Data} | {error, Reason}</name> <fsummary>Equivalent to receive_response(SSH, ChannelId, close).</fsummary> <desc><marker id="receive_response-2"/> @@ -817,7 +817,7 @@ ChannelId, close)</c></seealso>.</p> </func> <func> - <name>receive_response(SSH, ChannelId, End) -> {ok, Data} | {error, Reason}</name> + <name since="">receive_response(SSH, ChannelId, End) -> {ok, Data} | {error, Reason}</name> <fsummary>Equivalent to receive_response(SSH, ChannelId, End, DefaultTimeout).</fsummary> <desc><marker id="receive_response-3"/> @@ -828,7 +828,7 @@ ChannelId, End, DefaultTimeout)</c></seealso>.</p> </func> <func> - <name>receive_response(SSH, ChannelId, End, Timeout) -> {ok, Data} | {timeout, Data} | {error, Reason}</name> + <name since="">receive_response(SSH, ChannelId, End, Timeout) -> {ok, Data} | {timeout, Data} | {error, Reason}</name> <fsummary>Receives expected data from server on the specified session channel.</fsummary> <type> @@ -853,7 +853,7 @@ ChannelId, End, DefaultTimeout)</c></seealso>.</p> <p>If <c>End</c> is a fun, this fun is called with one argument, the data value in a received <c>ssh_cm</c> message (see - <seealso marker="ssh:ssh_connection"><c>ssh:ssh_connection(3)</c></seealso>. + <seealso marker="ssh:ssh_connection"><c>ssh_connection(3)</c></seealso>. The fun is to return either <c>true</c> to end the receiving operation (and have the so far collected data returned) or <c>false</c> to wait for more data from the server. Even if a fun @@ -863,7 +863,7 @@ ChannelId, End, DefaultTimeout)</c></seealso>.</p> </func> <func> - <name>rename(SSH, OldName, NewName) -> Result</name> + <name since="">rename(SSH, OldName, NewName) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -872,12 +872,12 @@ ChannelId, End, DefaultTimeout)</c></seealso>.</p> </type> <desc><marker id="rename-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>rename(SSH, Server, OldName, NewName) -> Result</name> + <name since="">rename(SSH, Server, OldName, NewName) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -886,12 +886,12 @@ ChannelId, End, DefaultTimeout)</c></seealso>.</p> </type> <desc><marker id="rename-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>send(SSH, ChannelId, Data) -> ok | {error, Reason}</name> + <name since="">send(SSH, ChannelId, Data) -> ok | {error, Reason}</name> <fsummary>Equivalent to send(SSH, ChannelId, 0, Data, DefaultTimeout).</fsummary> <desc><marker id="send-3"/> @@ -901,7 +901,7 @@ ChannelId, End, DefaultTimeout)</c></seealso>.</p> </func> <func> - <name>send(SSH, ChannelId, Data, Timeout) -> ok | {error, Reason}</name> + <name since="">send(SSH, ChannelId, Data, Timeout) -> ok | {error, Reason}</name> <fsummary>Equivalent to send(SSH, ChannelId, 0, Data, Timeout).</fsummary> <desc><marker id="send-4"/> <p>Equivalent to <seealso marker="#send-5"><c>ct_ssh:send(SSH, @@ -910,7 +910,7 @@ ChannelId, End, DefaultTimeout)</c></seealso>.</p> </func> <func> - <name>send(SSH, ChannelId, Type, Data, Timeout) -> ok | {error, Reason}</name> + <name since="">send(SSH, ChannelId, Type, Data, Timeout) -> ok | {error, Reason}</name> <fsummary>Sends data to server on specified session channel.</fsummary> <type> <v>SSH = connection()</v> @@ -926,7 +926,7 @@ ChannelId, End, DefaultTimeout)</c></seealso>.</p> </func> <func> - <name>send_and_receive(SSH, ChannelId, Data) -> {ok, Data} | {error, Reason}</name> + <name since="">send_and_receive(SSH, ChannelId, Data) -> {ok, Data} | {error, Reason}</name> <fsummary>Equivalent to send_and_receive(SSH, ChannelId, Data, close).</fsummary> <desc><marker id="send_and_receive-3"/> @@ -937,7 +937,7 @@ ChannelId, End, DefaultTimeout)</c></seealso>.</p> </func> <func> - <name>send_and_receive(SSH, ChannelId, Data, End) -> {ok, Data} | {error, Reason}</name> + <name since="">send_and_receive(SSH, ChannelId, Data, End) -> {ok, Data} | {error, Reason}</name> <fsummary>Equivalent to send_and_receive(SSH, ChannelId, 0, Data, End, DefaultTimeout).</fsummary> <desc><marker id="send_and_receive-4"/> @@ -948,7 +948,7 @@ ChannelId, 0, Data, End, DefaultTimeout)</c></seealso>.</p> </func> <func> - <name>send_and_receive(SSH, ChannelId, Data, End, Timeout) -> {ok, Data} | {error, Reason}</name> + <name since="">send_and_receive(SSH, ChannelId, Data, End, Timeout) -> {ok, Data} | {error, Reason}</name> <fsummary>Equivalent to send_and_receive(SSH, ChannelId, 0, Data, End, Timeout).</fsummary> <desc><marker id="send_and_receive-5"/> @@ -959,7 +959,7 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </func> <func> - <name>send_and_receive(SSH, ChannelId, Type, Data, End, Timeout) -> {ok, Data} | {error, Reason}</name> + <name since="">send_and_receive(SSH, ChannelId, Type, Data, End, Timeout) -> {ok, Data} | {error, Reason}</name> <fsummary>Sends data to server on specified session channel and waits to receive the server response.</fsummary> <type> @@ -981,7 +981,7 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </func> <func> - <name>session_close(SSH, ChannelId) -> ok | {error, Reason}</name> + <name since="">session_close(SSH, ChannelId) -> ok | {error, Reason}</name> <fsummary>Closes an SSH session channel.</fsummary> <type> <v>SSH = connection()</v> @@ -994,7 +994,7 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </func> <func> - <name>session_open(SSH) -> {ok, ChannelId} | {error, Reason}</name> + <name since="">session_open(SSH) -> {ok, ChannelId} | {error, Reason}</name> <fsummary>Equivalent to session_open(SSH, DefaultTimeout).</fsummary> <desc><marker id="session_open-1"/> <p>Equivalent to @@ -1004,7 +1004,7 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </func> <func> - <name>session_open(SSH, Timeout) -> {ok, ChannelId} | {error, Reason}</name> + <name since="">session_open(SSH, Timeout) -> {ok, ChannelId} | {error, Reason}</name> <fsummary>Opens a channel for an SSH session.</fsummary> <type> <v>SSH = connection()</v> @@ -1018,7 +1018,7 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </func> <func> - <name>sftp_connect(SSH) -> {ok, Server} | {error, Reason}</name> + <name since="">sftp_connect(SSH) -> {ok, Server} | {error, Reason}</name> <fsummary>Starts an SFTP session on an already existing SSH connection.</fsummary> <type> @@ -1034,7 +1034,34 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </func> <func> - <name>subsystem(SSH, ChannelId, Subsystem) -> Status | {error, Reason}</name> + <name since="OTP 20.0">shell(SSH, ChannelId) -> ok | {error, Reason}</name> + <fsummary>Equivalent to shell(SSH, ChannelId, DefaultTimeout).</fsummary> + <desc><marker id="shell-2"/> + <p>Equivalent to + <seealso marker="#shell-3"><c>ct_ssh:shell(SSH, ChannelId, + DefaultTimeout)</c></seealso>.</p> + </desc> + </func> + + <func> + <name since="OTP 20.0">shell(SSH, ChannelId, Timeout) -> ok | {error, Reason}</name> + <fsummary>Requests that the user default shell is executed at the + server end.</fsummary> + <type> + <v>SSH = connection()</v> + <v>ChannelId = integer()</v> + <v>Timeout = integer()</v> + <v>Reason = term()</v> + </type> + <desc><marker id="shell-3"/> + <p>Requests that the user default shell (typically defined in + <c>/etc/passwd</c> in Unix systems) is executed at the + server end.</p> + </desc> + </func> + + <func> + <name since="">subsystem(SSH, ChannelId, Subsystem) -> Status | {error, Reason}</name> <fsummary>Equivalent to subsystem(SSH, ChannelId, Subsystem, DefaultTimeout).</fsummary> <desc><marker id="subsystem-3"/> @@ -1045,7 +1072,7 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </func> <func> - <name>subsystem(SSH, ChannelId, Subsystem, Timeout) -> Status | {error, Reason}</name> + <name since="">subsystem(SSH, ChannelId, Subsystem, Timeout) -> Status | {error, Reason}</name> <fsummary>Sends a request to execute a predefined subsystem.</fsummary> <type> <v>SSH = connection()</v> @@ -1061,7 +1088,7 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </func> <func> - <name>write(SSH, Handle, Data) -> Result</name> + <name since="">write(SSH, Handle, Data) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -1070,12 +1097,12 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </type> <desc><marker id="write-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>write(SSH, Server, Handle, Data) -> Result</name> + <name since="">write(SSH, Server, Handle, Data) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -1084,12 +1111,12 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </type> <desc><marker id="write-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>write_file(SSH, File, Iolist) -> Result</name> + <name since="">write_file(SSH, File, Iolist) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -1098,12 +1125,12 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </type> <desc><marker id="write_file-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>write_file(SSH, Server, File, Iolist) -> Result</name> + <name since="">write_file(SSH, Server, File, Iolist) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -1112,12 +1139,12 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </type> <desc><marker id="write_file-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>write_file_info(SSH, Name, Info) -> Result</name> + <name since="">write_file_info(SSH, Name, Info) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -1126,12 +1153,12 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </type> <desc><marker id="write_file_info-3"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> <func> - <name>write_file_info(SSH, Server, Name, Info) -> Result</name> + <name since="">write_file_info(SSH, Server, Name, Info) -> Result</name> <fsummary>For information and other types, see ssh_sftp(3).</fsummary> <type> <v>SSH = connection()</v> @@ -1140,7 +1167,7 @@ ChannelId, 0, Data, End, Timeout)</c></seealso>.</p> </type> <desc><marker id="write_file_info-4"/> <p>For information and other types, see - <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p> + <seealso marker="ssh:ssh_sftp"><c>ssh_sftp(3)</c></seealso>.</p> </desc> </func> </funcs> diff --git a/lib/common_test/doc/src/ct_telnet.xml b/lib/common_test/doc/src/ct_telnet.xml index 1de278d30c..76f5305c46 100644 --- a/lib/common_test/doc/src/ct_telnet.xml +++ b/lib/common_test/doc/src/ct_telnet.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>ct_telnet.xml</file> </header> - <module>ct_telnet</module> + <module since="">ct_telnet</module> <modulesummary>Common Test specific layer on top of Telnet client ct_telnet_client.erl</modulesummary> <description> @@ -198,14 +198,14 @@ <item><marker id="type-prompt_regexp"/> <p>Regular expression matching all possible prompts for a specific target type. <c>regexp</c> must not have any groups, that is, when - matching, <c>re:run/3</c> (in <c>STDLIB</c>) must return a list with + matching, <c>re:run/3</c> (in STDLIB) must return a list with one single element.</p></item> </taglist> </section> <funcs> <func> - <name>close(Connection) -> ok | {error, Reason}</name> + <name since="">close(Connection) -> ok | {error, Reason}</name> <fsummary>Closes the Telnet connection and stops the process managing it.</fsummary> <type> @@ -223,7 +223,7 @@ </func> <func> - <name>cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}</name> + <name since="">cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}</name> <fsummary>Equivalent to cmd(Connection, Cmd, []).</fsummary> <desc><marker id="cmd-2"/> <p>Equivalent to @@ -233,24 +233,27 @@ </func> <func> - <name>cmd(Connection, Cmd, Opts) -> {ok, Data} | {error, Reason}</name> + <name since="">cmd(Connection, Cmd, Opts) -> {ok, Data} | {error, Reason}</name> <fsummary>Sends a command through Telnet and waits for prompt.</fsummary> <type> <v>Connection = connection()</v> <v>Cmd = string()</v> <v>Opts = [Opt]</v> - <v>Opt = {timeout, timeout()} | {newline, boolean()}</v> + <v>Opt = {timeout, timeout()} | {newline, boolean() | string()}</v> <v>Data = [string()]</v> <v>Reason = term()</v> </type> <desc><marker id="cmd-3"/> <p>Sends a command through Telnet and waits for prompt.</p> - <p>By default, this function adds a new line to the end of the + <p>By default, this function adds "\n" to the end of the specified command. If this is not desired, use option <c>{newline,false}</c>. This is necessary, for example, when sending Telnet command sequences prefixed with character - Interprete As Command (IAC).</p> + Interpret As Command (IAC). Option <c>{newline,string()}</c> + can also be used if a different line end than "\n" is + required, for instance <c>{newline,"\r\n"}</c>, to add both + carriage return and newline characters.</p> <p>Option <c>timeout</c> specifies how long the client must wait for prompt. If the time expires, the function returns @@ -262,7 +265,7 @@ </func> <func> - <name>cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}</name> + <name since="">cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}</name> <fsummary>Equivalent to cmdf(Connection, CmdFormat, Args, []).</fsummary> <desc><marker id="cmdf-3"/> <p>Equivalent to @@ -272,7 +275,7 @@ </func> <func> - <name>cmdf(Connection, CmdFormat, Args, Opts) -> {ok, Data} | {error, Reason}</name> + <name since="">cmdf(Connection, CmdFormat, Args, Opts) -> {ok, Data} | {error, Reason}</name> <fsummary>Sends a Telnet command and waits for prompt (uses a format string and a list of arguments to build the command).</fsummary> <type> @@ -280,7 +283,7 @@ <v>CmdFormat = string()</v> <v>Args = list()</v> <v>Opts = [Opt]</v> - <v>Opt = {timeout, timeout()} | {newline, boolean()}</v> + <v>Opt = {timeout, timeout()} | {newline, boolean() | string()}</v> <v>Data = [string()]</v> <v>Reason = term()</v> </type> @@ -294,7 +297,7 @@ </func> <func> - <name>expect(Connection, Patterns) -> term()</name> + <name since="">expect(Connection, Patterns) -> term()</name> <fsummary>Equivalent to expect(Connections, Patterns, []).</fsummary> <desc><marker id="expect-2"/> <p>Equivalent to @@ -304,7 +307,7 @@ </func> <func> - <name>expect(Connection, Patterns, Opts) -> {ok, Match} | {ok, MatchList, HaltReason} | {error, Reason}</name> + <name since="">expect(Connection, Patterns, Opts) -> {ok, Match} | {ok, MatchList, HaltReason} | {error, Reason}</name> <fsummary>Gets data from Telnet and waits for the expected pattern.</fsummary> <type> @@ -337,9 +340,9 @@ <c>FullMatch</c> is the string matched by the whole regular expression, and <c>SubMatchN</c> is the string that matched subexpression number <c>N</c>. Subexpressions are denoted with - <c>(' ')</c> in the regular expression.</p> + <c>'(' ')'</c> in the regular expression.</p> - <p>If a <c>Tag</c> is speciifed, the returned <c>Match</c> also + <p>If a <c>Tag</c> is specified, the returned <c>Match</c> also includes the matched <c>Tag</c>. Otherwise, only <c>RxMatch</c> is returned.</p> @@ -382,7 +385,7 @@ can abort the operation of waiting for prompt.</p></item> <tag><c>repeat | repeat, N</c></tag> <item><p>The pattern(s) must be matched multiple times. If <c>N</c> - is speciified, the pattern(s) are matched <c>N</c> times, and + is specified, the pattern(s) are matched <c>N</c> times, and the function returns <c>HaltReason = done</c>. This option can be interrupted by one or more <c>HaltPatterns</c>. <c>MatchList</c> is always returned, that is, a list of <c>Match</c> instead of @@ -422,7 +425,7 @@ </func> <func> - <name>get_data(Connection) -> {ok, Data} | {error, Reason}</name> + <name since="">get_data(Connection) -> {ok, Data} | {error, Reason}</name> <fsummary>Gets all data received by the Telnet client since the last command was sent.</fsummary> <type> @@ -446,7 +449,7 @@ </func> <func> - <name>open(Name) -> {ok, Handle} | {error, Reason}</name> + <name since="">open(Name) -> {ok, Handle} | {error, Reason}</name> <fsummary>Equivalent to open(Name, telnet).</fsummary> <desc><marker id="open-1"/> <p>Equivalent to @@ -456,7 +459,7 @@ </func> <func> - <name>open(Name, ConnType) -> {ok, Handle} | {error, Reason}</name> + <name since="">open(Name, ConnType) -> {ok, Handle} | {error, Reason}</name> <fsummary>Opens a Telnet connection to the specified target host.</fsummary> <type> @@ -471,7 +474,7 @@ </func> <func> - <name>open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}</name> + <name since="">open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}</name> <fsummary>Equivalent to open(KeyOrName, ConnType, TargetMod, []).</fsummary> <desc><marker id="open-3"/> <p>Equivalent to @@ -481,7 +484,7 @@ </func> <func> - <name>open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle} | {error, Reason}</name> + <name since="">open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle} | {error, Reason}</name> <fsummary>Opens a Telnet connection to the specified target host.</fsummary> <type> @@ -531,7 +534,7 @@ </func> <func> - <name>send(Connection, Cmd) -> ok | {error, Reason}</name> + <name since="">send(Connection, Cmd) -> ok | {error, Reason}</name> <fsummary>Equivalent to send(Connection, Cmd, []).</fsummary> <desc><marker id="send-2"/> <p>Equivalent to @@ -541,23 +544,26 @@ </func> <func> - <name>send(Connection, Cmd, Opts) -> ok | {error, Reason}</name> + <name since="OTP 17.4">send(Connection, Cmd, Opts) -> ok | {error, Reason}</name> <fsummary>Sends a Telnet command and returns immediately.</fsummary> <type> <v>Connection = connection()</v> <v>Cmd = string()</v> <v>Opts = [Opt]</v> - <v>Opt = {newline, boolean()}</v> + <v>Opt = {newline, boolean() | string()}</v> <v>Reason = term()</v> </type> <desc><marker id="send-3"/> <p>Sends a Telnet command and returns immediately.</p> - <p>By default, this function adds a newline to the end of the + <p>By default, this function adds "\n" to the end of the specified command. If this is not desired, option <c>{newline,false}</c> can be used. This is necessary, for example, when sending Telnet command sequences prefixed with character - Interprete As Command (IAC).</p> + Interpret As Command (IAC). Option <c>{newline,string()}</c> + can also be used if a different line end than "\n" is + required, for instance <c>{newline,"\r\n"}</c>, to add both + carriage return and newline characters.</p> <p>The resulting output from the command can be read with <seealso marker="#get_data-1"><c>ct_telnet:get_data/2</c></seealso> or @@ -566,7 +572,7 @@ </func> <func> - <name>sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}</name> + <name since="">sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}</name> <fsummary>Equivalent to sendf(Connection, CmdFormat, Args, []).</fsummary> <desc><marker id="sendf-3"/> <p>Equivalent to @@ -576,7 +582,7 @@ </func> <func> - <name>sendf(Connection, CmdFormat, Args, Opts) -> ok | {error, Reason}</name> + <name since="OTP 17.4">sendf(Connection, CmdFormat, Args, Opts) -> ok | {error, Reason}</name> <fsummary>Sends a Telnet command and returns immediately (uses a format string and a list of arguments to build the command).</fsummary> <type> @@ -584,12 +590,15 @@ <v>CmdFormat = string()</v> <v>Args = list()</v> <v>Opts = [Opt]</v> - <v>Opt = {newline, boolean()}</v> + <v>Opt = {newline, boolean() | string()}</v> <v>Reason = term()</v> </type> <desc><marker id="sendf-4"/> <p>Sends a Telnet command and returns immediately (uses a format string and a list of arguments to build the command).</p> + + <p>For details, see + <seealso marker="#send-3"><c>ct_telnet:send/3</c></seealso>.</p> </desc> </func> </funcs> diff --git a/lib/common_test/doc/src/ct_testspec.xml b/lib/common_test/doc/src/ct_testspec.xml new file mode 100644 index 0000000000..9cb9a2ae9f --- /dev/null +++ b/lib/common_test/doc/src/ct_testspec.xml @@ -0,0 +1,84 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2016</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>ct_testspec</title> + <prepared></prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date></date> + <rev>A</rev> + <file>ct_testspec.xml</file> + </header> + <module since="OTP 19.3">ct_testspec</module> + <modulesummary>Parsing of test specifications for Common Test. + </modulesummary> + +<description> + + <p>Parsing of test specifications for <c>Common Test</c>.</p> + + <p>This module exports help functions for parsing of test specifications.</p> + +</description> + + <funcs> + <func> + <name since="OTP 19.3">get_tests(SpecsIn) -> {ok, [{Specs,Tests}]} | {error, Reason}</name> + <fsummary>Parse the given test specification files and return the tests to run and skip.</fsummary> + <type> + <v>SpecsIn = [string()] | [[string()]]</v> + <v>Specs = [string()]</v> + <v>Test = [{Node,Run,Skip}]</v> + <v>Node = atom()</v> + <v>Run = {Dir,Suites,Cases}</v> + <v>Skip = {Dir,Suites,Comment} | {Dir,Suites,Cases,Comment}</v> + <v>Dir = string()</v> + <v>Suites = atom | [atom()] | all</v> + <v>Cases = atom | [atom()] | all</v> + <v>Comment = string()</v> + <v>Reason = term()</v> + </type> + <desc><marker id="add_nodes-1"/> + <p>Parse the given test specification files and return the + tests to run and skip.</p> + + <p>If <c>SpecsIn=[Spec1,Spec2,...]</c>, separate tests will be + created per specification. If + <c>SpecsIn=[[Spec1,Spec2,...]]</c>, all specifications will be + merge into one test.</p> + + <p>For each test, a <c>{Specs,Tests}</c> element is returned, + where <c>Specs</c> is a list of all included test + specifications, and <c>Tests</c> specifies actual tests to + run/skip per node.</p> + </desc> + </func> + + </funcs> + +</erlref> + + diff --git a/lib/common_test/doc/src/dependencies_chapter.xml b/lib/common_test/doc/src/dependencies_chapter.xml index 29c54e819a..8ede822ae5 100644 --- a/lib/common_test/doc/src/dependencies_chapter.xml +++ b/lib/common_test/doc/src/dependencies_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2006</year><year>2013</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/event_handler_chapter.xml b/lib/common_test/doc/src/event_handler_chapter.xml index 31128a7114..bd9ed21cb4 100644 --- a/lib/common_test/doc/src/event_handler_chapter.xml +++ b/lib/common_test/doc/src/event_handler_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2006</year><year>2013</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -50,7 +50,7 @@ pass the information on. The event handlers are Erlang modules implemented by the <c>Common Test</c> user according to the <c>gen_event</c> behavior (for details, see module - <seealso marker="stdlib:gen_event"><c>stdlib:gen_event</c></seealso> and + <seealso marker="stdlib:gen_event"><c>gen_event</c></seealso> and section <seealso marker="doc/design_principles:events"><c>gen_event Behaviour</c></seealso> in OTP Design Principles in the System Documentation). @@ -69,8 +69,8 @@ manager, either by telling <c>Common Test</c> to install them before the test run (described later), or by adding the handlers dynamically during the test run using - <seealso marker="stdlib:gen_event#add_handler-3"><c>stdlib:gen_event:add_handler/3</c></seealso> or - <seealso marker="stdlib:gen_event#add_sup_handler-3"><c>stdlib:gen_event:add_sup_handler/3</c></seealso>. + <seealso marker="stdlib:gen_event#add_handler-3"><c>gen_event:add_handler/3</c></seealso> or + <seealso marker="stdlib:gen_event#add_sup_handler-3"><c>gen_event:add_sup_handler/3</c></seealso>. In the latter scenario, the reference of the <c>Common Test</c> event manager is required. To get it, call <seealso marker="ct#get_event_mgr_ref-0"><c>ct:get_event_mgr_ref/0</c></seealso> diff --git a/lib/common_test/doc/src/example_chapter.xml b/lib/common_test/doc/src/example_chapter.xml index 8523c9f485..b82d14d2d8 100644 --- a/lib/common_test/doc/src/example_chapter.xml +++ b/lib/common_test/doc/src/example_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/fascicules.xml b/lib/common_test/doc/src/fascicules.xml deleted file mode 100644 index c4a28a699a..0000000000 --- a/lib/common_test/doc/src/fascicules.xml +++ /dev/null @@ -1,18 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> - -<fascicules> - <fascicule file="part" href="part_frame.html" entry="no"> - User's Guide - </fascicule> - <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> - Reference Manual - </fascicule> - <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> - Release Notes - </fascicule> - <fascicule file="" href="../../../../doc/print.html"> - Off-Print - </fascicule> -</fascicules> - diff --git a/lib/common_test/doc/src/getting_started_chapter.xml b/lib/common_test/doc/src/getting_started_chapter.xml index 802f9ba397..9b021058e8 100644 --- a/lib/common_test/doc/src/getting_started_chapter.xml +++ b/lib/common_test/doc/src/getting_started_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2007</year><year>2013</year> + <year>2007</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/install_chapter.xml b/lib/common_test/doc/src/install_chapter.xml index 9dce1e31a4..b29906d381 100644 --- a/lib/common_test/doc/src/install_chapter.xml +++ b/lib/common_test/doc/src/install_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2007</year><year>2013</year> + <year>2007</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/introduction.xml b/lib/common_test/doc/src/introduction.xml index e2a42bfd33..df12bea6dd 100644 --- a/lib/common_test/doc/src/introduction.xml +++ b/lib/common_test/doc/src/introduction.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -45,7 +45,7 @@ </list> <p><c>Common Test</c> also integrates use of the OTP <seealso marker="tools:cover">cover</seealso> tool in application - <c>Tools</c> for code coverage analysis of Erlang/OTP programs.</p> + Tools for code coverage analysis of Erlang/OTP programs.</p> <p><c>Common Test</c> executes test suite programs automatically, without operator interaction. Test progress and results are diff --git a/lib/common_test/doc/src/notes.xml b/lib/common_test/doc/src/notes.xml index 791be61066..38fdc2442e 100644 --- a/lib/common_test/doc/src/notes.xml +++ b/lib/common_test/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2013</year> + <year>2004</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -33,6 +33,475 @@ <file>notes.xml</file> </header> +<section><title>Common_Test 1.16.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The Logger handler cth_log_redirect earlier called the + report callback (report_cb) before calling the logger + formatter. In some cases this would fail, since + cth_log_redirect could not handle report callbacks with + two arguments. This is now corrected, so only the + formatter will call the report callback.</p> + <p> + Own Id: OTP-15307</p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.16</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Use the compiler option <c>nowarn_export_all</c> to + disable <c>export_all</c> warnings when automatically + compiling test suites.</p> + <p> + Own Id: OTP-14810</p> + </item> + <item> + <p> + Use uri_string module instead of http_uri.</p> + <p> + Own Id: OTP-14902</p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.15.4.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The status of a test case which failed with timetrap + timeout in <c>end_per_testcase</c> could not be modified + by returning <c>{fail,Reason}</c> from a + <c>post_end_per_testcase</c> hook function. This is now + corrected.</p> + <p> + Own Id: OTP-15584 Aux Id: ERIERL-282 </p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.15.4.0.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The status of a test case which failed with timetrap + timeout in <c>end_per_testcase</c> could not be modified + by returning <c>{fail,Reason}</c> from a + <c>post_end_per_testcase</c> hook function. This is now + corrected.</p> + <p> + Own Id: OTP-15584 Aux Id: ERIERL-282 </p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.15.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed problem with 'skip_groups' in combination with 'all + suites' option in test specification.</p> + <p> + Own Id: OTP-14953</p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.15.3</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + A new function, <c>ct:remaining_test_procs/0</c>, returns + the identity of test- and group leader processes that are + still running at the time of the call.</p> + <p> + Own Id: OTP-13832</p> + </item> + <item> + <p> + A "latest test result" link is now displayed in the + footer of each test index page, which performs a jump to + the most recently generated test index. This is useful + for making quick comparisons of results between test runs + without having to traverse the log file tree.</p> + <p> + Own Id: OTP-14281</p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.15.2</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + General Unicode improvements.</p> + <p> + Own Id: OTP-14462</p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.15.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + In OTP-20.0, the behavior of c, make, and ct_make was + changed so that in some cases the beam files by default + would be written to the directory where the source files + were found. This is now changed back to the old behavior + so beam files are by default written to current + directory.</p> + <p> + Own Id: OTP-14489 Aux Id: ERL-438 </p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.15</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Errors in the documentation for user HTML stylesheets + have been corrected.</p> + <p> + Own Id: OTP-14332 Aux Id: seq13299 </p> + </item> + <item> + <p>Internal code change: Calls to <c>catch</c> followed + by a call to <c>erlang:get_stacktrace/0</c> has been + rewritten to use <c>try</c> instead of <c>catch</c> to + make the code future-proof.</p> + <p> + Own Id: OTP-14400</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>The <c>ct_slave</c> modules now handle nodenames in + the same way as nodenames passed to <c>-sname</c>. That + means <c>ct_slave:start('[email protected]').</c> will now + work.</p> + <p> + Own Id: OTP-13806</p> + </item> + <item> + <p> + Added the new option, <c>keep_logs</c>. If setting the + value for this option to an integer, N, common_test will + remove all ct_run.* directories in the current log + directory, except the N newest.</p> + <p> + Own Id: OTP-14179</p> + </item> + <item> + <p> + The existing <c>ct_netconfc:open/1,2</c> opens an SSH + connection with one SSH channel realizing one Netconf + session. To allow testing of multiple sessions over the + same SSH connection, the following functions are added to + <c>ct_netconfc</c>:</p> + <p> + * <c>connect/1,2</c> - establish an SSH connection * + <c>disconnect/1</c> - close the given SSH connection * + <c>session/1,2,3</c> - open an ssh channel on the given + connection and send 'hello' to start a Netconf session</p> + <p> + Own Id: OTP-14284</p> + </item> + <item> + <p> Miscellaneous updates due to atoms containing + arbitrary Unicode characters. </p> + <p> + Own Id: OTP-14285</p> + </item> + <item> + <p> + The function ct_ssh:shell/2,3 is added.</p> + <p> + Own Id: OTP-14415 Aux Id: seq13315 </p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.14</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>The following corrections and improvements are done in + the common_test hook handling:</p> <list> <item> <p>An + extra argument, <c>Suite</c>, is added as the first + argument to each of the following hook callback + functions:</p> <list> + <item><c>pre_init_per_group</c></item> + <item><c>post_init_per_group</c></item> + <item><c>pre_end_per_group</c></item> + <item><c>post_end_per_group</c></item> + <item><c>pre_init_per_testcase</c></item> + <item><c>post_init_per_testcase</c></item> + <item><c>pre_end_per_testcase</c></item> + <item><c>post_end_per_testcase</c></item> + <item><c>on_tc_fail</c></item> + <item><c>on_tc_skip</c></item> </list> <p>For backwards + compatibility, if the new function is not exported from a + hook callback module, <c>common_test</c> will fall back + to the old interface and call the function without the + <c>Suite</c> argument.</p> </item> <item> <p>If either + <c>init_per_suite</c> or <c>end_per_suite</c> exists, but + not the other, then the non-existing function will be + reported as failed with reason <c>undef</c> in the test + log. The same goes for <c>init/end_per_group</c>. This + has always been a requirement according to the user's + guide, but now <c>common_test</c> is more explicit in the + report.</p> </item> <item> <p>If <c>init_per_suite</c> + was exported from a test suite, but not + <c>end_per_suite</c>, then <c>pre/post_end_per_suite</c> + was called with <c>Suite=ct_framework</c> instead of the + correct suite name. This is now corrected.</p> </item> + <item> <p>If <c>end_per_group</c> was exported from a + suite, but not <c>init_per_group</c>, then + <c>end_per_group</c> was never called. This is now + corrected.</p> </item> <item> <p>Tests that were skipped + before calling <c>pre_init_per_*</c> got faulty calls to + the corresponding <c>post_init_per_*</c>. E.g. if a test + was skipped because <c>suite/0</c> failed, then + <c>post_init_per_suite</c> would be called even though + <c>pre_init_per_suite</c> and <c>init_per_suite</c> were + not called. This is now corrected so a <c>post_*</c> + callback will never be called unless the corresponding + <c>pre_*</c> callback has been called first.</p> </item> + <item> <p>Tests that were skipped before or in + <c>init_per_testcase</c> got faulty calls to + <c>pre_end_per_testcase</c> and + <c>post_end_per_testcase</c>. This is now corrected so + <c>pre/post_end_per_testcase</c> are not called when + <c>end_per_testcase</c> is not called.</p> </item> <item> + <p>If an exit signal causes the test case process to die + while running <c>init_per_testcase</c>, the case was + earlier reported as failed with reason <c>{skip,...}</c>. + This is now corrected so the case will be marked as + skipped.</p> </item> <item> <p>If an exist signal causes + the test case process to die while running + <c>end_per_testcase</c>, the case was earlier marked as + failed. This is now corrected so the status of the test + case is not changed - there is only a warning added to + the comment field.</p> </item> <item> <p>If a test case + was skipped because of option + <c>{force_stop,skip_rest}</c> or because of a failed + sequence, then no <c>tc_start</c> event would be sent, + only <c>tc_done</c>. This is now corrected so both events + are sent.</p> </item> <item> <p>When skipping or failing + in a configuration function, the configuration function + itself would get <c>{auto_skipped,Reason}</c>, + <c>{skipped,Reason}</c> or <c>{failed,Reason}</c> in the + hook callbacks <c>on_tc_skip</c> or <c>on_tc_fail</c>. + The other test cases that were skipped as a result of + this would only get <c>Reason</c> in <c>on_tc_skip</c>. + This is now corrected so even the configuration function + that caused the skip/fail will only get <c>Reason</c> in + the hook callback.</p> </item> </list> + <p> + Own Id: OTP-10599 Aux Id: kunagi-344 [255] </p> + </item> + <item> + <p> + When a test case was skipped by a <c>skip_cases</c> + statement in a test spec, then <c>cth_surefire</c> would + erroneously mark the previous test case as skipped in the + xml report. The actually skipped test case would not be + present in the xml report at all. This is now corrected.</p> + <p> + Own Id: OTP-14129 Aux Id: seq13244 </p> + </item> + <item> + <p>The <c>multiply_timetraps</c> and + <c>scale_timetraps</c> options did not work with test + specifications, which has been corrected.</p> + <p> + Own Id: OTP-14210</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + ct_testspec:get_tests/1 is added. This is used by rebar3 + to get all directories that must be compiled when running + tests from testspec - instead of implementing testspec + parsing in rebar3.</p> + <p> + Own Id: OTP-14132</p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.13</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Some types of printouts to screen during test runs + (including <c>ct:print/1,2,3,4</c>) used the local + <c>user</c> process as IO device and these printouts + would not be visible when e.g. running tests via a shell + on a remote node. A default Common Test group leader + process has been introduced to solve the problem. This + process routes printouts to the group leader of the + starting process, if available, otherwise to <c>user</c>.</p> + <p> + Own Id: OTP-13973 Aux Id: ERL-279 </p> + </item> + <item> + <p> + Some Common Test processes, that act as I/O group leaders + for test cases, would not terminate as expected at the + end of test runs. This error has been corrected.</p> + <p> + Own Id: OTP-14026 Aux Id: ERL-287 </p> + </item> + <item> + <p> + The logging verbosity feature was incorrectly documented. + The default verbosity levels for test runs is e.g. not 50 + (<c>?STD_VERBOSITY</c>), but 100 (<c>?MAX_VERBOSITY</c>). + Also, some of the examples had errors and flaws. The + corresponding chapter (5.18) in the User's Guide has been + updated.</p> + <p> + Own Id: OTP-14044 Aux Id: seq13223 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + A feature to let the user specify headings to log + printouts has been added. The heading is specified as + <c>{heading,string()}</c> in the <c>Opts</c> list + argument to <c>ct:pal/3,4,5</c>, <c>ct:print/3,4,5</c>, + or <c>ct:log/3,4,5</c>. If the heading option is omitted, + the category name, or <c>"User"</c>, is used as the + heading instead.</p> + <p> + Own Id: OTP-14043 Aux Id: seq13226 </p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.12.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + If the telnet server would pause during transmission of a + line of text before terminating the line, the + <c>ct_telnet:expect/3</c> function would print the line + twice in the test case HTML log. This problem has been + fixed.</p> + <p> + Own Id: OTP-13730 Aux Id: seq13135 </p> + </item> + <item> + <p> + The functions <c>ct:set_verbosity/2</c> and + <c>ct:get_verbosity/1</c> have been added in order to + make it possible for test cases, CT Hooks, or test + framework functions, to modify and read verbosity levels + for logging.</p> + <p> + Own Id: OTP-13841</p> + </item> + <item> + <p><c>make</c> (tools) and <c>ct_make</c> (common_test) + would crash if an Erlang source file contained a + <c>-warning()</c> directive.</p> + <p> + Own Id: OTP-13855</p> + </item> + </list> + </section> + +</section> + +<section><title>Common_Test 1.12.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The following modules were missing in + common_test.app.src: ct_groups, ct_property_test, + ct_release_test, ct_webtool, ct_webtool_sup, + test_server_gl. They have now been added.</p> + <p> + Own Id: OTP-13475</p> + </item> + <item> + <p> + Common Test printed incorrect timestamps for received + error reports.</p> + <p> + Own Id: OTP-13615 Aux Id: seq13124 </p> + </item> + </list> + </section> + +</section> + <section><title>Common_Test 1.12.1</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -3595,8 +4064,3 @@ <section><title>common_test 1.3.0</title> </section> </chapter> - - - - - diff --git a/lib/common_test/doc/src/notes_history.xml b/lib/common_test/doc/src/notes_history.xml index ecc0cab651..3a30632579 100644 --- a/lib/common_test/doc/src/notes_history.xml +++ b/lib/common_test/doc/src/notes_history.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2013</year> + <year>2004</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/part.xml b/lib/common_test/doc/src/part.xml index 41e74e57c6..000eb06b82 100644 --- a/lib/common_test/doc/src/part.xml +++ b/lib/common_test/doc/src/part.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/part_notes.xml b/lib/common_test/doc/src/part_notes.xml deleted file mode 100644 index 3d55d8152d..0000000000 --- a/lib/common_test/doc/src/part_notes.xml +++ /dev/null @@ -1,41 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part xmlns:xi="http://www.w3.org/2001/XInclude"> - <header> - <copyright> - <year>2004</year><year>2013</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>Common Test</title> - <prepared>Peter Andersson</prepared> - <docno></docno> - <date>2007-12-01</date> - <rev></rev> - <file>part_notes.xml</file> - </header> - <description> - <p>Common Test - tool for automated testing, based on the Erlang/OTP Test Server.</p> - <p>For information about older versions see - <url href="part_notes_history_frame.html">release notes - history</url>.</p> - </description> - <xi:include href="notes.xml"/> -</part> - - diff --git a/lib/common_test/doc/src/part_notes_history.xml b/lib/common_test/doc/src/part_notes_history.xml deleted file mode 100644 index 1e503ce536..0000000000 --- a/lib/common_test/doc/src/part_notes_history.xml +++ /dev/null @@ -1,35 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part> - <header> - <copyright> - <year>2004</year><year>2013</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>Common Test</title> - <prepared>Peter Andersson</prepared> - <docno></docno> - <date>2007-12-01</date> - <rev></rev> - <file>part_notes.xml</file> - </header> - <include file="notes_history"></include> -</part> - - diff --git a/lib/common_test/doc/src/ref_man.xml b/lib/common_test/doc/src/ref_man.xml index 19960bfea7..1ac20db5c2 100644 --- a/lib/common_test/doc/src/ref_man.xml +++ b/lib/common_test/doc/src/ref_man.xml @@ -4,7 +4,7 @@ <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -47,6 +47,7 @@ <xi:include href="ct_slave.xml"/> <xi:include href="ct_hooks.xml"/> <xi:include href="ct_property_test.xml"/> + <xi:include href="ct_testspec.xml"/> </application> diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml index e5e217ca1d..56f6f7bcc4 100644 --- a/lib/common_test/doc/src/run_test_chapter.xml +++ b/lib/common_test/doc/src/run_test_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -274,7 +274,7 @@ <note><p>Directories passed to <c>Common Test</c> can have either relative or absolute paths.</p></note> - <note><p>Any start flags to the Erlang runtime system (application <c>ERTS</c>) can also be passed as + <note><p>Any start flags to the Erlang runtime system (application ERTS) can also be passed as parameters to <c>ct_run</c>. It is, for example, useful to be able to pass directories to be added to the Erlang code server search path with flag <c>-pa</c> or <c>-pz</c>. If you have common help- or library @@ -286,7 +286,7 @@ <p>The absolute path of directory <c>chat_server/ebin</c> is here passed to the code server. This is essential because relative paths are stored by the code server as relative, and <c>Common Test</c> changes - the current working directory of <c>ERTS</c> during the test run.</p> + the current working directory of ERTS during the test run.</p> </note> <p>The <c>ct_run</c> program sets the exit status before shutting down. The following values @@ -1258,7 +1258,7 @@ <p>The minor log files contain full details of every single test case, each in a separate file. This way, it is straightforward to compare the latest results to that of previous - test runs, even if the set of test cases changes. If application <c>SASL</c> + test runs, even if the set of test cases changes. If application SASL is running, its logs are also printed to the current minor log file by the <seealso marker="common_test:ct_hooks_chapter#builtin_cths"> cth_log_redirect built-in hook</seealso>. @@ -1322,8 +1322,8 @@ <title>The Unexpected I/O Log</title> <p>The test suites overview page includes a link to the Unexpected I/O Log. In this log, <c>Common Test</c> saves printouts made with - <seealso marker="ct#log-2"><c>ct:log/2</c></seealso> and - <seealso marker="ct#pal-2"><c>ct:pal/2</c></seealso>, as well as captured system + <seealso marker="ct#log-2"><c>ct:log/1,2,3,4,5</c></seealso> and + <seealso marker="ct#pal-2"><c>ct:pal/1,2,3,4,5</c></seealso>, as well as captured system error- and progress reports, which cannot be associated with particular test cases and therefore cannot be written to individual test case log files. This occurs, for example, if a log printout is made from an external process (not a test @@ -1338,7 +1338,7 @@ <title>The Pre- and Post Test I/O Log</title> <p>The <c>Common Test</c> Framework Log page includes links to the Pre- and Post Test I/O Log. In this log, <c>Common Test</c> saves printouts made - with <c>ct:log/2</c> and <c>ct:pal/2</c>, as well as captured system error- + with <c>ct:log/1,2,3,4,5</c> and <c>ct:pal/1,2,3,4,5</c>, as well as captured system error- and progress reports, which take place before, and after, the test run. Examples of this are printouts from a CT hook init- or terminate function, or progress reports generated when an OTP application is started from a CT hook @@ -1349,10 +1349,22 @@ applications, see section <seealso marker="ct_hooks_chapter#synchronizing">Synchronizing</seealso> in section Common Test Hooks.</p> - <note><p>Logging to file with <c>ct:log/2</c> or <c>ct:pal/2</c> - only works when <c>Common Test</c> is running. Printouts with <c>ct:pal/2</c> + <note><p>Logging to file with <c>ct:log/1,2,3,4,5</c> or <c>ct:pal/1,2,3,4,5</c> + only works when <c>Common Test</c> is running. Printouts with <c>ct:pal/1,2,3,4,5</c> are however always displayed on screen.</p></note> </section> + + <section> + <marker id="delete_old_logs"></marker> + <title>Delete Old Logs</title> + <p><c>Common Test</c> can automatically delete old log. This + is specified with the <c>keep_logs</c> option. The default + value for this option is <c>all</c>, which means that no + logs are deleted. If the value is set to an + integer, <c>N</c>, <c>Common Test</c> deletes + all <c>ct_run.<timestamp></c> directories, except + the <c>N</c> newest.</p> + </section> </section> <section> @@ -1371,24 +1383,38 @@ <p><c>Common Test</c> includes an <em>optional</em> feature to allow user HTML style sheets for customizing printouts. The functions in <c>ct</c> that print to a test case HTML log - file (<c>log/3</c> and <c>pal/3</c>) accept <c>Category</c> + file (<c>log/3,4,5</c> and <c>pal/3,4,5</c>) accept <c>Category</c> as first argument. With this argument a category can be specified - that can be mapped to a selector in a CSS - definition. This is useful, especially for coloring text + that can be mapped to a named <c>div</c> selector in a CSS rule-set. + This is useful, especially for coloring text differently depending on the type of (or reason for) the - printout. Say you want one color for test system + printout. Say you want one particular background color for test system configuration information, a different one for test system state information, and finally one for errors detected by the test case functions. The corresponding style sheet can look as follows:</p> <pre> - div.sys_config { background:blue; color:white } - div.sys_state { background:yellow; color:black } - div.error { background:red; color:white }</pre> + div.sys_config { background:blue } + div.sys_state { background:yellow } + div.error { background:red }</pre> + + <p>Common Test prints the text from <c>ct:log/3,4,5</c> or + <c>ct:pal/3,4,5</c> inside a <c>pre</c> element + nested under the named <c>div</c> element. Since the <c>pre</c> selector + has a predefined CSS rule (in file <c>ct_default.css</c>) for the attributes + <c>color</c>, <c>font-family</c> and <c>font-size</c>, if a user wants to + change any of the predefined attribute settings, a new rule for <c>pre</c> + must be added to the user stylesheet. Example:</p> + + <pre> +div.error pre { color:white }</pre> + + <p>Here, white text is used instead of the default black for <c>div.error</c> + printouts (and no other attribute settings for <c>pre</c> are affected).</p> <p>To install the CSS file (<c>Common Test</c> inlines the definition in the - HTML code), the name can be provided when executing <c>ct_run</c>.</p> + HTML code), the file name can be provided when executing <c>ct_run</c>.</p> <p><em>Example:</em></p> <pre> @@ -1436,8 +1462,8 @@ suite.</p> <p>Argument <c>Category</c> in the previous example can have the - value (atom) <c>sys_config</c> (white on blue), <c>sys_state</c> - (black on yellow), or <c>error</c> (white on red).</p> + value (atom) <c>sys_config</c> (blue background), <c>sys_state</c> + (yellow background), or <c>error</c> (white text on red background).</p> </section> <section> diff --git a/lib/common_test/doc/src/specs.xml b/lib/common_test/doc/src/specs.xml new file mode 100644 index 0000000000..7e40e8351d --- /dev/null +++ b/lib/common_test/doc/src/specs.xml @@ -0,0 +1,5 @@ +<?xml version="1.0" encoding="utf-8" ?> +<specs xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include href="../specs/specs_ct_netconfc.xml"/> + <xi:include href="../specs/specs_ct.xml"/> +</specs> diff --git a/lib/common_test/doc/src/test_structure_chapter.xml b/lib/common_test/doc/src/test_structure_chapter.xml index 8076244928..3ffaa623c3 100644 --- a/lib/common_test/doc/src/test_structure_chapter.xml +++ b/lib/common_test/doc/src/test_structure_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2006</year><year>2013</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/unix_telnet.xml b/lib/common_test/doc/src/unix_telnet.xml index a064a222d6..03d91b7dbe 100644 --- a/lib/common_test/doc/src/unix_telnet.xml +++ b/lib/common_test/doc/src/unix_telnet.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2010</year><year>2012</year> + <year>2010</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>unix_telnet.xml</file> </header> - <module>unix_telnet</module> + <module since="">unix_telnet</module> <modulesummary>Callback module for ct_telnet, for connecting to a Telnet server on a UNIX host.</modulesummary> @@ -80,7 +80,7 @@ <funcs> <func> - <name>connect(ConnName, Ip, Port, Timeout, KeepAlive, TCPNoDelay, Extra) -> {ok, Handle} | {error, Reason}</name> + <name since="OTP 18.3.3">connect(ConnName, Ip, Port, Timeout, KeepAlive, TCPNoDelay, Extra) -> {ok, Handle} | {error, Reason}</name> <fsummary>Callback for ct_telnet.erl.</fsummary> <type> <v>ConnName = target_name()</v> @@ -107,7 +107,7 @@ </func> <func> - <name>get_prompt_regexp() -> PromptRegexp</name> + <name since="">get_prompt_regexp() -> PromptRegexp</name> <fsummary>Callback for ct_telnet.erl.</fsummary> <type> <v>PromptRegexp = prompt_regexp()</v> diff --git a/lib/common_test/doc/src/why_test_chapter.xml b/lib/common_test/doc/src/why_test_chapter.xml index ff6000628b..cdac4e04b2 100644 --- a/lib/common_test/doc/src/why_test_chapter.xml +++ b/lib/common_test/doc/src/why_test_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml index a7a652d506..82dc06834f 100644 --- a/lib/common_test/doc/src/write_test_chapter.xml +++ b/lib/common_test/doc/src/write_test_chapter.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -269,10 +269,10 @@ <p>As parameter <c>Config</c> is a list of key-value tuples, that is, a data type called a property list, it can be handled by the - <seealso marker="stdlib:proplists"><c>stdlib:proplists</c></seealso> module. + <seealso marker="stdlib:proplists"><c>proplists</c></seealso> module. A value can, for example, be searched for and returned with function <seealso marker="stdlib:proplists#get_value-2"><c>proplists:get_value/2</c></seealso>. - Also, or alternatively, the general <seealso marker="stdlib:lists"><c>stdlib:lists</c></seealso> + Also, or alternatively, the general <seealso marker="stdlib:lists"><c>lists</c></seealso> module contains useful functions. Normally, the only operations performed on <c>Config</c> is insert (adding a tuple to the head of the list) and lookup. <c>Common Test</c> provides a simple macro named <c>?config</c>, @@ -566,7 +566,7 @@ for the test cases in the group. After execution of the group is finished, function <seealso marker="common_test#Module:end_per_group-2"><c>end_per_group(GroupName, Config)</c></seealso> is called. This function is meant to be used for cleaning up after - <c>init_per_group/2</c>.</p> + <c>init_per_group/2</c>. If the init function is defined, so must the end function be.</p> <p>Whenever a group is executed, if <c>init_per_group</c> and <c>end_per_group</c> do not exist in the suite, <c>Common Test</c> calls @@ -652,7 +652,7 @@ <title>Parallel Test Cases and I/O</title> <p>A parallel test case has a private I/O server as its group leader. (For a description of the group leader concept, see - <seealso marker="erts:index"><c>ERTS</c></seealso>). + <seealso marker="erts:index">ERTS</seealso>). The central I/O server process, which handles the output from regular test cases and configuration functions, does not respond to I/O messages during execution of parallel groups. This is important to understand @@ -986,15 +986,17 @@ <c>io:put_chars/1</c>, and so on.</p> <p><c>Importance</c> is compared to a verbosity level set by the - <c>verbosity</c> start flag/option. The verbosity level can be set per - category or generally, or both. The default verbosity level, - <c>?STD_VERBOSITY</c>, is 50, that is, all standard I/O gets printed. - If a lower verbosity level is set, standard I/O printouts are ignored. - <c>Common Test</c> performs the following test:</p> + <c>verbosity</c> start flag/option. The level can be set per + category or generally, or both. If <c>verbosity</c> is not set by the user, + a level of 100 (<c>?MAX_VERBOSITY</c> = all printouts visible) is used as + default value. <c>Common Test</c> performs the following test:</p> <pre> - Importance >= (100-VerbosityLevel)</pre> - <p>This also means that verbosity level 0 effectively turns all logging off - (except from printouts made by <c>Common Test</c> itself).</p> +Importance >= (100-VerbosityLevel)</pre> + <p>The constant <c>?STD_VERBOSITY</c> has value 50 (see <c>ct.hrl</c>). + At this level, all standard I/O gets printed. If a lower verbosity level + is set, standard I/O printouts are ignored. Verbosity level 0 effectively + turns all logging off (except from printouts made by <c>Common Test</c> + itself).</p> <p>The general verbosity level is not associated with any particular category. This level sets the threshold for the standard I/O printouts, @@ -1003,17 +1005,17 @@ <p><em>Examples:</em></p> <p>Some printouts during test case execution:</p> - <pre> + <pre> io:format("1. Standard IO, importance = ~w~n", [?STD_IMPORTANCE]), ct:log("2. Uncategorized, importance = ~w", [?STD_IMPORTANCE]), - ct:log(info, "3. Categorized info, importance = ~w", [?STD_IMPORTANCE]]), + ct:log(info, "3. Categorized info, importance = ~w", [?STD_IMPORTANCE]), ct:log(info, ?LOW_IMPORTANCE, "4. Categorized info, importance = ~w", [?LOW_IMPORTANCE]), - ct:log(error, "5. Categorized error, importance = ~w", [?HI_IMPORTANCE]), - ct:log(error, ?HI_IMPORTANCE, "6. Categorized error, importance = ~w", [?MAX_IMPORTANCE]),</pre> + ct:log(error, ?HI_IMPORTANCE, "5. Categorized error, importance = ~w", [?HI_IMPORTANCE]), + ct:log(error, ?MAX_IMPORTANCE, "6. Categorized error, importance = ~w", [?MAX_IMPORTANCE]),</pre> - <p>If starting the test without specifying any verbosity levels as follows:</p> + <p>If starting the test with a general verbosity level of 50 (<c>?STD_VERBOSITY</c>):</p> <pre> - $ ct_run ...</pre> + $ ct_run -verbosity 50</pre> <p>the following is printed:</p> <pre> 1. Standard IO, importance = 50 @@ -1031,9 +1033,25 @@ 4. Categorized info, importance = 25 6. Categorized error, importance = 99</pre> + <p>Note that the category argument is not required in order to only specify the + importance of a printout. Example:</p> + <pre> +ct:pal(?LOW_IMPORTANCE, "Info report: ~p", [Info])</pre> + <p>Or perhaps in combination with constants:</p> + <pre> +-define(INFO, ?LOW_IMPORTANCE). +-define(ERROR, ?HI_IMPORTANCE). + +ct:log(?INFO, "Info report: ~p", [Info]) +ct:pal(?ERROR, "Error report: ~p", [Error])</pre> + + <p>The functions <seealso marker="ct#set_verbosity-2"><c>ct:set_verbosity/2</c></seealso> + and <seealso marker="ct#get_verbosity-1"><c>ct:get_verbosity/1</c></seealso> may be used + to modify and read verbosity levels during test execution.</p> + <p>The arguments <c>Format</c> and <c>FormatArgs</c> in <c>ct:log/print/pal</c> are - always passed on to the <c>stdlib</c> function <c>io:format/3</c> (For details, - see the <seealso marker="stdlib:io"><c>stdlib:io</c></seealso> manual page).</p> + always passed on to the STDLIB function <c>io:format/3</c> (For details, + see the <seealso marker="stdlib:io"><c>io</c></seealso> manual page).</p> <p><c>ct:pal/4</c> and <c>ct:log/5</c> add headers to strings being printed to the log file. The strings are also wrapped in div tags with a CSS class |