Gitweb links: ...log http://git.netsurf-browser.org/netsurf.git/shortlog/06b709f71a7e1ac2bb2b1... ...commit http://git.netsurf-browser.org/netsurf.git/commit/06b709f71a7e1ac2bb2b17d... ...tree http://git.netsurf-browser.org/netsurf.git/tree/06b709f71a7e1ac2bb2b17d99... The branch, master has been updated via 06b709f71a7e1ac2bb2b17d99bd155e4a993963d (commit) via 5bc21c0467b2e6c8ed44f72c7ed42c7ebc4ce5ae (commit) from fa1f1dcd1188ab80803b1ef0773020d1378dbfc4 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- commitdiff http://git.netsurf-browser.org/netsurf.git/commit/?id=06b709f71a7e1ac2bb2... commit 06b709f71a7e1ac2bb2b17d99bd155e4a993963d Author: Vincent Sanders <vince(a)kyllikki.org&gt; Commit: Vincent Sanders <vince(a)kyllikki.org&gt; Improve unit testing documentation headers and code blocks diff --git a/docs/unit-testing.md b/docs/unit-testing.md index 49d82ed..054c8e5 100644 --- a/docs/unit-testing.md +++ b/docs/unit-testing.md @@ -1,8 +1,9 @@ NetSurf Unit Testing ==================== -Overview --------- +[toc] + +# Overview NetSurf has unit tests integrated in the test directory. These tests use the check unit test framework for C [1]. @@ -13,8 +14,7 @@ programs although the framework does not madate this and some test programs contain more than one suite. -Execution ---------- +# Execution The test programs are executed by using the standard "test" target from the top level make invocation. The "coverage" target additionally @@ -25,8 +25,7 @@ The check library must be installed to run the tests and the CI system automatically executes all enabled tests and generates coverage reports for each commit. -Adding tests ------------- +# Adding tests The test/Makefile defines each indiviadual test program that should be built and executed in the TESTS variable. @@ -39,128 +38,128 @@ Each individual test program requires a main function which creates one (or more) suites. The suites are added to a test runner and then executed and the results reported. -int main(int argc, char **argv) -{ - int number_failed; - SRunner *sr; - - sr = srunner_create(foo_suite_create()); - //srunner_add_suite(sr, bar_suite_create()); - - srunner_run_all(sr, CK_ENV); - - number_failed = srunner_ntests_failed(sr); - srunner_free(sr); - - return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE; -} + int main(int argc, char **argv) + { + int number_failed; + SRunner *sr; + + sr = srunner_create(foo_suite_create()); + //srunner_add_suite(sr, bar_suite_create()); + + srunner_run_all(sr, CK_ENV); + + number_failed = srunner_ntests_failed(sr); + srunner_free(sr); + + return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE; + } Suite creation is done with a sub function to logically split suite code into sub modules. Each suite has test cases added to it. -Suite *foo_suite_create(void) -{ - Suite *s; - s = suite_create("foo"); - - suite_add_tcase(s, baz_case_create()); - suite_add_tcase(s, qux_case_create()); - - return s; -} + Suite *foo_suite_create(void) + { + Suite *s; + s = suite_create("foo"); + + suite_add_tcase(s, baz_case_create()); + suite_add_tcase(s, qux_case_create()); + + return s; + } Test cases include the actual tests to be performed within each case. -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_test(tc, xxyz_test); - tcase_add_test(tc, zzyx_test); - - return tc; -} + TCase *baz_case_create(void) + { + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_test(tc, xxyz_test); + tcase_add_test(tc, zzyx_test); + + return tc; + } A test case may optionally have a fixture which is code that is executed before and after each test case. Unchecked fixtures are executed once before the test process forks for each test whereas checked fixtures are executed for each and every test. -static void fixture_setup(void) -{ -} - -static void fixture_teardown(void) -{ -} - -TCase *qux_case_create(void) -{ - TCase *tc; - - /* Matching entry tests */ - tc = tcase_create("Match"); - - tcase_add_checked_fixture(tc, - fixture_setup, - fixture_teardown); - - tcase_add_test(tc, zzz_test); - - return tc; -} + static void fixture_setup(void) + { + } + + static void fixture_teardown(void) + { + } + + TCase *qux_case_create(void) + { + TCase *tc; + + /* Matching entry tests */ + tc = tcase_create("Match"); + + tcase_add_checked_fixture(tc, + fixture_setup, + fixture_teardown); + + tcase_add_test(tc, zzz_test); + + return tc; + } Additionally test cases can contain tests executed in a loop. The test recives a single integer as a parameter named _i which iterates between values specified in the case setup. -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_loop_test(tc, looping_test, 0, 5); - - return tc; -} + TCase *baz_case_create(void) + { + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_loop_test(tc, looping_test, 0, 5); + + return tc; + } It is also possible to create tests which will generate a signal. The most commonly used of these is to check asserts in API calls. -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_test_raise_signal(tc, assert_test, 6); - - return tc; -} + TCase *baz_case_create(void) + { + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_test_raise_signal(tc, assert_test, 6); + + return tc; + } Actual test code is self contained in a function which uses the ck_assert macros to test results. The check framework requires each test to use the START_TEST and END_TEST macros when definig them. -/** - * url access leaf test - */ -START_TEST(nsurl_access_leaf_test) -{ - nserror err; - nsurl *res_url; - const struct test_triplets *tst = &access_tests[_i]; - - /* not testing create, this should always succeed */ - err = nsurl_create(tst->test1, &res_url); - ck_assert(err == NSERROR_OK); - - ck_assert_str_eq(nsurl_access_leaf(res_url), tst->res); - - nsurl_unref(res_url); -} -END_TEST + /** + * url access leaf test + */ + START_TEST(nsurl_access_leaf_test) + { + nserror err; + nsurl *res_url; + const struct test_triplets *tst = &access_tests[_i]; + + /* not testing create, this should always succeed */ + err = nsurl_create(tst->test1, &res_url); + ck_assert(err == NSERROR_OK); + + ck_assert_str_eq(nsurl_access_leaf(res_url), tst->res); + + nsurl_unref(res_url); + } + END_TEST [1] https://libcheck.github.io/check/ commitdiff http://git.netsurf-browser.org/netsurf.git/commit/?id=5bc21c0467b2e6c8ed4... commit 5bc21c0467b2e6c8ed44f72c7ed42c7ebc4ce5ae Author: Vincent Sanders <vince(a)kyllikki.org&gt; Commit: Vincent Sanders <vince(a)kyllikki.org&gt; fix use of headings in integration test document diff --git a/docs/integration-testing.md b/docs/integration-testing.md index defcc17..1191fba 100644 --- a/docs/integration-testing.md +++ b/docs/integration-testing.md @@ -1,8 +1,9 @@ NetSurf Integration Testing =========================== -Overview --------- +[TOC] + +# Overview The monkey frontend is used to perform complex tests involving operating the browser as a user might (opening windows, navigating to @@ -26,8 +27,7 @@ known behaviours such as delays or returning specific content to extend test capabilities. -Running a test --------------- +# Running a test An individual test can be run using the monkey_driver.py python script from within the NetSurf repository @@ -43,8 +43,7 @@ For example to wrap execution under valgrind memory checker $ ./test/monkey_driver.py -m ./nsmonkey -w 'valgrind -v --track-origins=yes' -t test/monkey-tests/start-stop.yaml -Running more than one test --------------------------- +# Running more than one test Each test is a member of a group and the tests within each group are run together. Groups are listed within division index files. A group @@ -88,8 +87,7 @@ group to be executed. => Run test: resource-scheme.yaml PASS -Test files ----------- +# Test files Each test is a individual [YAML](https://en.wikipedia.org/wiki/YAML) file and consists of associative arrays (key/value pairs), lists and @@ -114,10 +112,9 @@ then quits it without ever opening a window to browse to a page - action: quit -Actions -------- +# Actions -### launch +## launch Start a browser instance. A test will generally have a single launch action paired with a quit action. @@ -145,18 +142,19 @@ The following launch action would start a browser: * The user options `enable_javascript` and `send_referer` set to false. * The `LANGUAGE` environment variable set to `en` - - action: launch - launch-options: - - verbose - environment: - NETSURFRES: /home/netsurf/resources - options: - - enable_javascript=0 - - send_referer=0 - language: en - +``` +- action: launch + launch-options: + - verbose + environment: + NETSURFRES: /home/netsurf/resources + options: + - enable_javascript=0 + - send_referer=0 + language: en +``` -### window-new +## window-new Open a new browser window. The test may open as many browser windows as necessary and they are usually paired with a `window-close` action @@ -175,7 +173,7 @@ referred to with the win1 identifier: tag: win1 -### window-close +## window-close Closes a previously opened window. The window is identified with the `window` key, the value of this must be a previously created window @@ -185,7 +183,7 @@ identifier or an assert will occur. window: win1 -### navigate +## navigate Cause a window to start navigating to a new URL. @@ -215,7 +213,7 @@ navigation in a loop with different values. repeaturl: urls -### reload +## reload Cause a window to (re)navigate to the current URL @@ -226,7 +224,7 @@ assert will occur. - action: reload window: win1 -### stop +## stop Cause a window to immediately stop any navigation. @@ -237,7 +235,7 @@ assert will occur. - action: stop window: win1 -### sleep-ms +## sleep-ms Wait for time to pass before continuing to next action. @@ -280,7 +278,7 @@ action is delaying. - action: quit -### block +## block Wait for conditions to be met before continuing. This is similar to the `sleep-ms` action except that it will wait forever for the @@ -295,7 +293,7 @@ terminate the block. status: complete -### repeat +## repeat Repeat a set of actions. @@ -354,7 +352,7 @@ Note that `min` ,`step` and `max` are ignored if there is a `values` key status: complete -### timer-start +## timer-start Start a timer. @@ -364,7 +362,7 @@ The identifier for the timer is set with the `timer` key. timer: timer1 -### timer-restart +## timer-restart Re-start a timer @@ -373,7 +371,8 @@ The identifier for the timer is set with the `timer` key. - action: timer-restart timer: timer1 -### timer-stop + +## timer-stop Stop a timer @@ -383,7 +382,7 @@ The identifier for the timer is set with the `timer` key. timer: timer1 -### timer-check +## timer-check Check a timer meets a condition. @@ -392,7 +391,7 @@ The identifier for the timer is set with the `timer` key. The conditional is set with the `condition` key which must be present. -### plot-check +## plot-check Perform a plot of a previously navigated window. @@ -422,7 +421,7 @@ The checks available are: - bitmap-count: 1 -### click +## click Perform a user mouse click on a specified window. @@ -449,7 +448,7 @@ not specified is `single` text: "about:Choices" -### wait-loading +## wait-loading Wait for the navigated page to start loading before moving to the next action. @@ -462,7 +461,7 @@ assert will occur. window: win1 -### add-auth +## add-auth Add basic authentication details for a navigation. @@ -478,7 +477,7 @@ answer the challenge. password: bar -### remove-auth +## remove-auth Remove a previously added authentication details. @@ -489,17 +488,17 @@ Remove a previously added authentication details. password: bar -### add-cert +## add-cert Add certificate error handler for a url. -### remove-cert +## remove-cert Remove certificate error handler for a url. -### clear-log +## clear-log Clear log for a window. @@ -508,7 +507,7 @@ value of this must be a previously created window identifier or an assert will occur. -### wait-log +## wait-log Wait for string to appear in log output. @@ -518,7 +517,7 @@ assert will occur. The keys `source` `foldable` `level` and `substring` must be specified -### js-exec +## js-exec Execute javascript in a window. @@ -529,7 +528,7 @@ assert will occur. The `cmd` key contains the javascript to execute. -### page-info-state +## page-info-state Check the page information status matches an expected value. @@ -540,6 +539,6 @@ assert will occur. The value of the `match` key is compared to the windows page information status and an assert occurs if there is a mismatch. -### quit +## quit This causes a previously launched browser instance to exit cleanly. ----------------------------------------------------------------------- Summary of changes: docs/integration-testing.md | 89 ++++++++++--------- docs/unit-testing.md | 199 +++++++++++++++++++++---------------------- 2 files changed, 143 insertions(+), 145 deletions(-) diff --git a/docs/integration-testing.md b/docs/integration-testing.md index defcc17..1191fba 100644 --- a/docs/integration-testing.md +++ b/docs/integration-testing.md @@ -1,8 +1,9 @@ NetSurf Integration Testing =========================== -Overview --------- +[TOC] + +# Overview The monkey frontend is used to perform complex tests involving operating the browser as a user might (opening windows, navigating to @@ -26,8 +27,7 @@ known behaviours such as delays or returning specific content to extend test capabilities. -Running a test --------------- +# Running a test An individual test can be run using the monkey_driver.py python script from within the NetSurf repository @@ -43,8 +43,7 @@ For example to wrap execution under valgrind memory checker $ ./test/monkey_driver.py -m ./nsmonkey -w 'valgrind -v --track-origins=yes' -t test/monkey-tests/start-stop.yaml -Running more than one test --------------------------- +# Running more than one test Each test is a member of a group and the tests within each group are run together. Groups are listed within division index files. A group @@ -88,8 +87,7 @@ group to be executed. => Run test: resource-scheme.yaml PASS -Test files ----------- +# Test files Each test is a individual [YAML](https://en.wikipedia.org/wiki/YAML) file and consists of associative arrays (key/value pairs), lists and @@ -114,10 +112,9 @@ then quits it without ever opening a window to browse to a page - action: quit -Actions -------- +# Actions -### launch +## launch Start a browser instance. A test will generally have a single launch action paired with a quit action. @@ -145,18 +142,19 @@ The following launch action would start a browser: * The user options `enable_javascript` and `send_referer` set to false. * The `LANGUAGE` environment variable set to `en` - - action: launch - launch-options: - - verbose - environment: - NETSURFRES: /home/netsurf/resources - options: - - enable_javascript=0 - - send_referer=0 - language: en - +``` +- action: launch + launch-options: + - verbose + environment: + NETSURFRES: /home/netsurf/resources + options: + - enable_javascript=0 + - send_referer=0 + language: en +``` -### window-new +## window-new Open a new browser window. The test may open as many browser windows as necessary and they are usually paired with a `window-close` action @@ -175,7 +173,7 @@ referred to with the win1 identifier: tag: win1 -### window-close +## window-close Closes a previously opened window. The window is identified with the `window` key, the value of this must be a previously created window @@ -185,7 +183,7 @@ identifier or an assert will occur. window: win1 -### navigate +## navigate Cause a window to start navigating to a new URL. @@ -215,7 +213,7 @@ navigation in a loop with different values. repeaturl: urls -### reload +## reload Cause a window to (re)navigate to the current URL @@ -226,7 +224,7 @@ assert will occur. - action: reload window: win1 -### stop +## stop Cause a window to immediately stop any navigation. @@ -237,7 +235,7 @@ assert will occur. - action: stop window: win1 -### sleep-ms +## sleep-ms Wait for time to pass before continuing to next action. @@ -280,7 +278,7 @@ action is delaying. - action: quit -### block +## block Wait for conditions to be met before continuing. This is similar to the `sleep-ms` action except that it will wait forever for the @@ -295,7 +293,7 @@ terminate the block. status: complete -### repeat +## repeat Repeat a set of actions. @@ -354,7 +352,7 @@ Note that `min` ,`step` and `max` are ignored if there is a `values` key status: complete -### timer-start +## timer-start Start a timer. @@ -364,7 +362,7 @@ The identifier for the timer is set with the `timer` key. timer: timer1 -### timer-restart +## timer-restart Re-start a timer @@ -373,7 +371,8 @@ The identifier for the timer is set with the `timer` key. - action: timer-restart timer: timer1 -### timer-stop + +## timer-stop Stop a timer @@ -383,7 +382,7 @@ The identifier for the timer is set with the `timer` key. timer: timer1 -### timer-check +## timer-check Check a timer meets a condition. @@ -392,7 +391,7 @@ The identifier for the timer is set with the `timer` key. The conditional is set with the `condition` key which must be present. -### plot-check +## plot-check Perform a plot of a previously navigated window. @@ -422,7 +421,7 @@ The checks available are: - bitmap-count: 1 -### click +## click Perform a user mouse click on a specified window. @@ -449,7 +448,7 @@ not specified is `single` text: "about:Choices" -### wait-loading +## wait-loading Wait for the navigated page to start loading before moving to the next action. @@ -462,7 +461,7 @@ assert will occur. window: win1 -### add-auth +## add-auth Add basic authentication details for a navigation. @@ -478,7 +477,7 @@ answer the challenge. password: bar -### remove-auth +## remove-auth Remove a previously added authentication details. @@ -489,17 +488,17 @@ Remove a previously added authentication details. password: bar -### add-cert +## add-cert Add certificate error handler for a url. -### remove-cert +## remove-cert Remove certificate error handler for a url. -### clear-log +## clear-log Clear log for a window. @@ -508,7 +507,7 @@ value of this must be a previously created window identifier or an assert will occur. -### wait-log +## wait-log Wait for string to appear in log output. @@ -518,7 +517,7 @@ assert will occur. The keys `source` `foldable` `level` and `substring` must be specified -### js-exec +## js-exec Execute javascript in a window. @@ -529,7 +528,7 @@ assert will occur. The `cmd` key contains the javascript to execute. -### page-info-state +## page-info-state Check the page information status matches an expected value. @@ -540,6 +539,6 @@ assert will occur. The value of the `match` key is compared to the windows page information status and an assert occurs if there is a mismatch. -### quit +## quit This causes a previously launched browser instance to exit cleanly. diff --git a/docs/unit-testing.md b/docs/unit-testing.md index 49d82ed..054c8e5 100644 --- a/docs/unit-testing.md +++ b/docs/unit-testing.md @@ -1,8 +1,9 @@ NetSurf Unit Testing ==================== -Overview --------- +[toc] + +# Overview NetSurf has unit tests integrated in the test directory. These tests use the check unit test framework for C [1]. @@ -13,8 +14,7 @@ programs although the framework does not madate this and some test programs contain more than one suite. -Execution ---------- +# Execution The test programs are executed by using the standard "test" target from the top level make invocation. The "coverage" target additionally @@ -25,8 +25,7 @@ The check library must be installed to run the tests and the CI system automatically executes all enabled tests and generates coverage reports for each commit. -Adding tests ------------- +# Adding tests The test/Makefile defines each indiviadual test program that should be built and executed in the TESTS variable. @@ -39,128 +38,128 @@ Each individual test program requires a main function which creates one (or more) suites. The suites are added to a test runner and then executed and the results reported. -int main(int argc, char **argv) -{ - int number_failed; - SRunner *sr; - - sr = srunner_create(foo_suite_create()); - //srunner_add_suite(sr, bar_suite_create()); - - srunner_run_all(sr, CK_ENV); - - number_failed = srunner_ntests_failed(sr); - srunner_free(sr); - - return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE; -} + int main(int argc, char **argv) + { + int number_failed; + SRunner *sr; + + sr = srunner_create(foo_suite_create()); + //srunner_add_suite(sr, bar_suite_create()); + + srunner_run_all(sr, CK_ENV); + + number_failed = srunner_ntests_failed(sr); + srunner_free(sr); + + return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE; + } Suite creation is done with a sub function to logically split suite code into sub modules. Each suite has test cases added to it. -Suite *foo_suite_create(void) -{ - Suite *s; - s = suite_create("foo"); - - suite_add_tcase(s, baz_case_create()); - suite_add_tcase(s, qux_case_create()); - - return s; -} + Suite *foo_suite_create(void) + { + Suite *s; + s = suite_create("foo"); + + suite_add_tcase(s, baz_case_create()); + suite_add_tcase(s, qux_case_create()); + + return s; + } Test cases include the actual tests to be performed within each case. -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_test(tc, xxyz_test); - tcase_add_test(tc, zzyx_test); - - return tc; -} + TCase *baz_case_create(void) + { + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_test(tc, xxyz_test); + tcase_add_test(tc, zzyx_test); + + return tc; + } A test case may optionally have a fixture which is code that is executed before and after each test case. Unchecked fixtures are executed once before the test process forks for each test whereas checked fixtures are executed for each and every test. -static void fixture_setup(void) -{ -} - -static void fixture_teardown(void) -{ -} - -TCase *qux_case_create(void) -{ - TCase *tc; - - /* Matching entry tests */ - tc = tcase_create("Match"); - - tcase_add_checked_fixture(tc, - fixture_setup, - fixture_teardown); - - tcase_add_test(tc, zzz_test); - - return tc; -} + static void fixture_setup(void) + { + } + + static void fixture_teardown(void) + { + } + + TCase *qux_case_create(void) + { + TCase *tc; + + /* Matching entry tests */ + tc = tcase_create("Match"); + + tcase_add_checked_fixture(tc, + fixture_setup, + fixture_teardown); + + tcase_add_test(tc, zzz_test); + + return tc; + } Additionally test cases can contain tests executed in a loop. The test recives a single integer as a parameter named _i which iterates between values specified in the case setup. -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_loop_test(tc, looping_test, 0, 5); - - return tc; -} + TCase *baz_case_create(void) + { + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_loop_test(tc, looping_test, 0, 5); + + return tc; + } It is also possible to create tests which will generate a signal. The most commonly used of these is to check asserts in API calls. -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_test_raise_signal(tc, assert_test, 6); - - return tc; -} + TCase *baz_case_create(void) + { + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_test_raise_signal(tc, assert_test, 6); + + return tc; + } Actual test code is self contained in a function which uses the ck_assert macros to test results. The check framework requires each test to use the START_TEST and END_TEST macros when definig them. -/** - * url access leaf test - */ -START_TEST(nsurl_access_leaf_test) -{ - nserror err; - nsurl *res_url; - const struct test_triplets *tst = &access_tests[_i]; - - /* not testing create, this should always succeed */ - err = nsurl_create(tst->test1, &res_url); - ck_assert(err == NSERROR_OK); - - ck_assert_str_eq(nsurl_access_leaf(res_url), tst->res); - - nsurl_unref(res_url); -} -END_TEST + /** + * url access leaf test + */ + START_TEST(nsurl_access_leaf_test) + { + nserror err; + nsurl *res_url; + const struct test_triplets *tst = &access_tests[_i]; + + /* not testing create, this should always succeed */ + err = nsurl_create(tst->test1, &res_url); + ck_assert(err == NSERROR_OK); + + ck_assert_str_eq(nsurl_access_leaf(res_url), tst->res); + + nsurl_unref(res_url); + } + END_TEST [1] https://libcheck.github.io/check/ -- NetSurf Browser