Executes the chunk of code associated with the component_id.

Call this function from within a testcase body only.

Parameters:

component_id (required)

Author:

Peter Harper

Created:

28 October 2001

Testcases:

db_check_news_create, db_check_news_archive, db_check_news_set_approve, db_check_news_status

# # Perform cleanup tests to check for object/command leaks in # either the called functions or in the test itself. #

Switches:

-silent (optional, boolean)

Parameters:

msg (optional, defaults to "final")

Testcases:

webtest_example

Displays either a pass or fail result with specified explanation depending on the given response.

Switches:

-response (required)

A boolean value where true (or 1, etc) corresponds to a pass result, otherwise the result is a fail.

-explanation (required)

An explanation accompanying the response.

Testcases:

fs_add_file_to_folder_twt, fs_add_file_to_folder

Tests that the affirm_actual is equal to affirm_value.

Call this function within a testcase, stub or component.

Parameters:

affirm_name (required)

affirm_actual (required)

affirm_value (required)

Returns:

True if the affirmation passed, false otherwise.

Author:

Peter Harper

Created:

24 July 2001

Testcases:

webtest_example, aa__coverage_proc_coverage, aa__coverage_proc_proc_list_covered, aa__coverage_proc_coverage_level

Writes an error message to the testcase log.

Call this function within a testcase, stub or component.

Parameters:

error_notes (required)

Author:

Peter Harper

Created:

04 November 2001

Testcases:

callgraph__bad_library_calls, callgraph__bad_page_calls, acs_subsite_expose_bug_775

Called from an initialization class constructor or a component to explicitly export the specified variables to the current testcase. You need to call aa_export_vars before you create the variables. Example:

    aa_export_vars {package_id item_id}
    set package_id 23
    set item_id 109
    

Parameters:

varnames (required)

Testcases:

db_check_news_create, db_check_news_archive, db_check_news_set_approve, db_check_news_status

Tests that affirm_expr is false. Call this function within a testcase, stub or component.

Parameters:

affirm_name (required)

affirm_expr (required)

Returns:

True if the affirmation passed, false otherwise.

Author:

Peter Harper

Created:

24 July 2001

Testcases:

webtest_example

Procedure for getting the URL of a mounted package with the package_key. It uses the first instance that it founds. This is useful for tclwebtest tests.

Switches:

-package_key (required)

Testcases:

fs_add_file_to_folder, web_forum_new, web_forum_view, web_forum_edit, web_forums_message_and_reply

Writes a log message to the testcase log. Call this function within a testcase, stub or component.

Author:

Peter Harper

Created:

24 July 2001

Testcases:

webtest_example

Log a test result

Parameters:

test_result (required)

Author:

Peter Harper

Created:

24 July 2001

Testcases:

datamodel__named_constraints, datamodel__acs_object_type_check, datamodel__acs_attribute_check, documentation__check_proc_doc, naming__proc_naming, documentation__check_deprecated_see, documentation__check_typos, documentation__check_parameters, files__check_info_files

Registers a testcase with the acs-automated-testing system. Whenever possible, cases that fail to register are replaced with 'metatest' log cases, so that the register-time errors are visible at test time. See the tutorial for examples.

Switches:

-libraries (optional)

A list of keywords of additional code modules to load. The entire test case will fail if any package is missing. Currently includes tclwebtest.

-cats (optional)

Properties of the test case. Must be zero or more of the following:

• db: Tests the database directly
• api: tests the Tcl API
• web: tests HTTP interface
• smoke: Minimal test to assure functionality and catch basic errors.
• stress: Puts heavy load on server or creates large numbers of records. Intended to simulate maximal production load.
• security_risk: May introduce a security risk.
• populator: Creates sample data for future use.
• production_safe: Can be used on a live production site, i.e. for sanity checking or keepalive purposes. Implies: no risk of adding or deleting data; no risk of crashing; minimal cpu/db/net load.

-error_level (optional, defaults to "error")

Force all test failures to this error level. One of

• notice: Informative. Does not indicate an error.
• warning: May indicate an problem. Example: a non-critical bug repro case that hasn't been fixed.
• error: normal error
• metatest: Indicates a problem with the test framework, execution, or reporting. Suggests that current test results may be invalid. Use this for test cases that test the tests. Also used, automatically, for errors sourcing test cases.

-bugs (optional)

A list of integers corresponding to openacs.org bug numbers which relate to this test case.

-procs (optional)

A list of OpenACS procs which are tested by this case.

-urls (optional)

A list of URLs (relative to package) tested in web test case

-init_classes (optional)

Deprecated.

-on_error (optional)

Deprecated.

Parameters:

testcase_id (required)

testcase_desc (required)

Author:

Peter Harper

Created:

24 July 2001

Testcases:

webtest_example, aa__coverage_proc_coverage, aa__coverage_proc_proc_list_covered, aa__coverage_proc_coverage_level

Registers a reusable code component. Provide a component identifier, description and component body code.

This is useful for reusing code that sets up / clears down, data common to many testcases.

Parameters:

component_id (required)

component_desc (required)

body (required)

Author:

Peter Harper

Created:

28 October 2001

Testcases:

db_check_news_create, db_check_news_archive, db_check_news_set_approve, db_check_news_status

Registers an initialization class to be used by one or more testcases. An initialization class can be assigned to a testcase via the aa_register_case proc. An initialization constructor is called once before running a set of testcases, and the destructor called once upon completion of running a set of testcases.

The idea behind this is that it could be used to perform data intensive operations that shared amongst a set if testcases. For example, mounting an instance of a package. This could be performed by each testcase individually, but this would be highly inefficient if there are any significant number of them. Better to let the acs-automated-testing infrastructure call the init_class code to set the package up, run all the tests, then call the destructor to unmount the package.

Parameters:

init_class_id (required)

Unique string to identify the init class

init_class_desc (required)

Longer description of the init class

constructor (required)

Tcl code block to run to setup the init class

destructor (required)

Tcl code block to tear down the init class

Author:

Peter Harper

Created:

04 November 2001

Testcases:

check_package_mount, db_check_news_create, db_check_news_revision, db_check_news_archive, db_check_news_set_approve, db_check_news_status

Execute code in test_code and guarantee that code in teardown_code will be executed even if error is thrown. Will catch errors in teardown_code as well and provide stack traces for both code blocks.

Switches:

-test_code (required)

Tcl code that sets up the test case and executes tests

-teardown_code (optional)

Tcl code that tears down database data etc. that needs to execute after testing even if error is thrown.

-rollback (optional, boolean)

If specified, any db transactions in test_code will be rolled back.

Author:

Peter Marklund

Testcases:

webtest_example

Writes a log message indicating a new section to the log files.

Parameters:

log_notes (required)

Testcases:

webtest_example

Silence expected messages in the system log. The proc deactivates the specified severity levels during the code in the last argument is executed. After it has finished, the severity levels are reset to their previous values.

Switches:

-severities (required)

Parameters:

code (required)

Testcases:

webtest_example, upgrade

Stubs a function. Provide the procedure name and the new body code.

Either call this function from within a testcase for a testcase specific stub, or outside a testcase for a file-wide stub.

Parameters:

proc_name (required)

new_body (required)

Author:

Peter Harper

Created:

24 July 2001

Testcases:

acs_admin_check_expired_certificates, auth_password_change, auth_password_recover, auth_password_reset, auth_use_email_for_login_p, auth_email_on_password_change, util__replace_temporary_tags_with_lookups

Processes the xml report outputted from install.sh for display.

Switches:

-path (required)

-array (required)

Testcases:

No testcase defined.

Processes the xml report with test result data for display.

Switches:

-path (required)

-array (required)

Testcases:

No testcase defined.

Retrieves the XMLReportDir parameter.

Returns:

Returns the value for the XMLReportDir parameter.

Testcases:

No testcase defined.

Check, if the regression test is currently running.

Returns:

boolean value indicating state

Testcases:

webtest_example

Set the start flag of the regression test case.

Testcases:

webtest_example

Tests that affirm_expr is true.

Call this function within a testcase, stub or component.

Parameters:

affirm_name (required)

affirm_expr (required)

Returns:

True if the affirmation passed, false otherwise.

Author:

Peter Harper

Created:

24 July 2001

Testcases:

webtest_example, aa__coverage_proc_coverage, aa__coverage_proc_proc_list_covered

Copies (back) a proc with "_unstubbed" suffix to its supposedly unpostfixed original name.

Parameters:

proc_name (required)

Author:

Peter Harper

Created:

24 July 2001

Testcases:

util__replace_temporary_tags_with_lookups

Confirms user email

Switches:

-user_id (required)

Testcases:

webtest_example, acs_subsite_test_email_confirmation

Parses HTML into a tDOM object and executes some code.

Parameters:

var (required)

the variable name that body can refer to as documentElement of the document (e.g. "root").

html (required)

the markup to be parsed.

body (required)

a Tcl script executed in the caller scope that can assume the document to be parsed and be available in "var".

Testcases:

markup_parsing, create_folder_with_page, link_tests, create_form_with_form_instance, create_form_with_numeric, form_validate, nested_self_references

Find the first link based on the provided label and return the href.

Switches:

-last_request (required)

-user_id (optional, defaults to "0")

-base (optional, defaults to "/")

-label (optional)

Author:

Gustaf Neumann

Testcases:

fs_add_file_to_folder

Follow the first provided label and return the page info. Probably, we want as well other mechanisms to locate the anchor element later.

Switches:

-last_request (required)

-user_id (optional, defaults to "0")

-base (optional, defaults to "/")

-label (optional)

Author:

Gustaf Neumann

Testcases:

fs_create_folder, fs_edit_folder, fs_add_file_to_folder

Get the fields from a form.

Parameters:

form (required)

Author:

Gustaf Neumann

See Also:

• acs::test::get_form

Testcases:

markup_parsing, create_folder_with_page, create_workflow_with_instance, create_form_with_form_instance

Check, if the form is empty

Parameters:

form (required)

Author:

Gustaf Neumann

See Also:

• acs::test::get_form

Testcases:

markup_parsing

Send a (POST) request to the specified URL based on the provided form_content which has the form of a dict. For convenience the update fields are provided to overload the form_content.

Switches:

-user_id (optional, defaults to "0")

-last_request (optional)

pass optionally the past request, from which cookie and login-info can be taken

-form (optional)

-url (optional)

-update (optional)

key/attribute list of values to be updated in the form content

-remove (optional)

keys to be removed from the form content

Parameters:

form_content (optional)

Testcases:

fs_add_file_to_folder, create_folder_with_page, create_form_with_form_instance

Set the fields in a form.

Parameters:

form (required)

fields (required)

Author:

Gustaf Neumann

See Also:

• acs::test::get_form

Testcases:

create_workflow_with_instance, create_form_with_form_instance

Locate the HTML forms matching the XPath expression and retrieve its HTML attributes and the formfields in form of a Tcl dict. This is a convenience function, combining acs::test::dom_html and ::acs::test::xpath::get_form.

Parameters:

body (required)

xpath (required)

Returns:

Tcl dict with form attributes (starting with "@" and fields)

Author:

Gustaf Neumann

See Also:

• acs::test::dom_html ::acs::test::xpath::get_form

Testcases:

markup_parsing, create_folder_with_page, create_form_with_form_instance

Determine the URL based on the location field provided from the result dict (as returned from acs::test::http).

Parameters:

dict (required)

dict containing an ns_set called headers

See Also:

• acs::test::http

Testcases:

fs_add_file_to_folder, create_folder_with_page, create_form_with_form_instance

Run an HTTP request against the actual server inside test cases.

Switches:

-user_id (optional, defaults to "0")

-user_info (optional)

-last_request (optional)

-method (optional, defaults to "GET")

-body (optional)

-timeout (optional, defaults to "10")

-depth (optional, defaults to "1")

follow redirects up to specified depth. Default means redirects won't be followed.

-headers (optional)

-prefix (optional)

-verbose (optional, boolean, defaults to "true")

-basic_auth (optional, boolean, defaults to "false")

Parameters:

request (required)

Author:

Gustaf Neumann

Testcases:

webtest_example, password_recovery_page, front_page_1, ad_context_bar_multirow, create_form_with_form_instance, create_form_with_numeric, form_validate, nested_self_references

Login (register operation) in a web session

Parameters:

user_info (required)

dict containing at least email, last_name, username and password

Testcases:

webtest_example

Logout from the current web session

Switches:

-last_request (required)

reply dict containing cookies

Testcases:

webtest_example

Convenience function for test cases to check, whether the resulting page contains the given string.

Switches:

-prefix (optional)

prefix for logging

Parameters:

dict (required)

request reply dict, containing at least the request body

string (required)

string to be checked on the page

Testcases:

webtest_example

Convenience function for test cases to check, whether the resulting page does not contain the given string.

Switches:

-prefix (optional)

prefix for logging

Parameters:

dict (required)

request reply dict, containing at least the request body

string (required)

string to be checked on the page

Testcases:

webtest_example

Convenience function for test cases to check, whether the reply has the given status code.

Switches:

-prefix (optional)

prefix for logging

Parameters:

dict (required)

request reply dict, containing at least the request status

status_code (required)

expected HTTP status codes

Testcases:

webtest_example, password_recovery_page, front_page_1, ad_context_bar_multirow, create_form_with_form_instance, create_form_with_numeric, form_validate, nested_self_references

Returns a test instance of specified package_key mounted under specified name. Will create it if it is not found. It is currently assumed the instance will be mounted under the main subsite.

Switches:

-package_key (required)

package to be instantiated

-instance_name (optional)

name of the site-node this instance will be mounted to. Will default to -test

-empty (optional, boolean)

require an empty instance. If an existing instance is found, it will be deleted. If a package different than is found, it won't be deleted and the proc will return an error

Returns:

a package_id

Testcases:

package_normalize_path, includelet_toc, includelet_childresources, link_tests, slot_interactions, path_resolve, create_form_with_form_instance, create_form_with_numeric, form_validate, nested_self_references

Returns:

the test URL representing our system for testing. This would normally look like the output of ns_conn location, unless it was overridden via the TestURL parameter in this package.

Testcases:

webtest_example

Create a test user with random email and password for testing. If an email is passed in and the party identified by the password exists, the user_id of this party is returned in the dict.

Switches:

-admin (optional, boolean)

provide this switch to make the user site-wide admin

-email (optional)

email for the user to be created

-locale (optional, defaults to "en_US")

locale for the user to be created

-password (optional)

password for the user to be created

-user_id (optional)

user_id for the user to be created

Returns:

The user_info dict returned by auth::create_user. Contains the additional keys email and password.

Testcases:

acs_admin_merge_MergeUserInfo, auth_authenticate, auth_create_user, auth_password_change, auth_password_reset, auth_email_on_password_change, webtest_example, acs_subsite_expose_bug_1144, acs_subsite_check_composite_group, acs_subsite_test_email_confirmation, community_cc_procs, demote_promote_a_user, ad_proc_change_state_member, ad_proc_permission_grant_and_revoke, ad_proc_permission_permission_p, calendar_basic_api, create_form_with_form_instance, create_form_with_numeric, form_validate, nested_self_references

Remove a test user.

Switches:

-user_id (required)

-delete_created_acs_objects (optional, boolean, defaults to "false")

Testcases:

webtest_example

Quotes and therefore makes visible control chars in input lines

Parameters:

lines (required)

Testcases:

visualize_control_chars

Test whether provided selectors (first element of the pair) return the specified results (second element of the pair).

Parameters:

node (required)

pairs (required)

Testcases:

markup_parsing

Locate the HTML forms matching the XPath expression and retrieve its HTML attributes and the formfields in form of a Tcl dict.

Parameters:

node (required)

xpath (required)

Returns:

Tcl dict with form attributes (keys starting with "@", and entry "fields")

Author:

Gustaf Neumann

Testcases:

markup_parsing, create_folder_with_page, create_form_with_form_instance

Obtain form values (input fields and textareas) in form of a dict (attribute value pairs). The provided XPath expression must point to the HTML form containing the values to be extracted.

Parameters:

node (required)

xpath (required)

Testcases:

create_folder_with_page, create_form_with_form_instance

Get a text element from tdom via XPath expression. If the XPath expression matches multiple nodes, return a list.

Parameters:

root (required)

xpath (required)

Testcases:

markup_parsing

Test if provided selectors return nonempty results

Parameters:

node (required)

selectors (required)

Testcases:

markup_parsing