summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorXavi Artigas <xavierartigas@yahoo.es>2020-04-01 18:40:40 +0200
committerXavi Artigas <xavierartigas@yahoo.es>2020-04-02 13:02:11 +0200
commit0122865ee18b13292267e246a66dfb862be96143 (patch)
treed627491585626268f59418e3e525decddbb54655
parent2ae0a9ff6250d898ce1a59205434696d9778bfe9 (diff)
exactness docs: Add docs, fix docs, remove docs
Summary: The Exactness tool needed usage instructions... and quite some more fixes. There was copypasta all around. Depends on D11634 Test Plan: Build and Enjoy Reviewers: bu5hm4n, stefan_schmidt Reviewed By: stefan_schmidt Subscribers: cedric, #reviewers, #committers Tags: #efl Differential Revision: https://phab.enlightenment.org/D11637
-rw-r--r--src/bin/exactness/exactness.c59
-rw-r--r--src/bin/exactness/exactness_play.in37
-rw-r--r--src/bin/exactness/exactness_record.in37
-rw-r--r--src/bin/exactness/inspect.c7
4 files changed, 96 insertions, 44 deletions
diff --git a/src/bin/exactness/exactness.c b/src/bin/exactness/exactness.c
index 6599ef7741..c99fceeb99 100644
--- a/src/bin/exactness/exactness.c
+++ b/src/bin/exactness/exactness.c
@@ -417,22 +417,51 @@ _errors_sort_cb(List_Entry *a, List_Entry *b)
417 417
418static const Ecore_Getopt optdesc = { 418static const Ecore_Getopt optdesc = {
419 "exactness", 419 "exactness",
420 "%prog [options] <-r|-p|-i|-s> <list file>", 420 "%prog [options] <-p|-i|-s> <test list file>",
421 PACKAGE_VERSION, 421 PACKAGE_VERSION,
422 "(C) 2013 Enlightenment", 422 "(C) 2013-2020 Enlightenment",
423 "BSD", 423 "BSD",
424 "A pixel perfect test suite for EFL based applications.", 424 "A pixel-perfect test suite for EFL-based applications.\n"
425 "\n"
426 "This binary allows running the individual tools `exactness_record` and\n"
427 "`exactness_play` in batch for a set of tests specified in a test list file.\n"
428 "\n"
429 "To obtain the reference templates (the \"golden\" files):\n"
430 "1.For each tested application, run `exactness_record` to launch the\n"
431 " application and record actions like keystrokes and mouse clicks.\n"
432 " This produces a test file with `.exu` extension.\n"
433 "2.Run `exactness` in init mode (-i) to execute the stored actions in all\n"
434 " the tests in the test list file and obtain screenshots.\n"
435 " The screenshots are embedded into the test `.exu` file.\n"
436 "\n"
437 "To check if the application currently matches the reference templates:\n"
438 "1.Run `exactness` in play mode (-p) to execute the stored actions in all\n"
439 " the tests in the test list file and compare the obtained screenshots\n"
440 " with the stored versions (the reference templates).\n"
441 " If mismatches are detected an error report is produced, including\n"
442 " a graphical diff of the screenshots.\n"
443 "\n"
444 "The test list file contains one line per test. Each line starts with the\n"
445 "test file name (without the `.exu` extension), a space and then the command\n"
446 "to execute, including parameters if any. # indicates a comment.\n"
447 "Example:\n"
448 "separator elementary_test -to Separator",
425 0, 449 0,
426 { 450 {
427 ECORE_GETOPT_APPEND('b', "base-dir", "The location of the exu files.", ECORE_GETOPT_TYPE_STR), 451 ECORE_GETOPT_APPEND('b', "base-dir", "The location of the exu files. Defaults to `./recordings/`.",
428 ECORE_GETOPT_STORE_STR('o', "output", "The location of the images."), 452 ECORE_GETOPT_TYPE_STR),
453 ECORE_GETOPT_STORE_STR('o', "output", "The location of the images. Defaults to `./`."),
429 ECORE_GETOPT_STORE_STR('w', "wrap", "Use a custom command to launch the tests (e.g valgrind)."), 454 ECORE_GETOPT_STORE_STR('w', "wrap", "Use a custom command to launch the tests (e.g valgrind)."),
430 ECORE_GETOPT_STORE_USHORT('j', "jobs", "The number of jobs to run in parallel."), 455 ECORE_GETOPT_STORE_USHORT('j', "jobs", "The number of jobs to run in parallel. Defaults to 1."),
431 ECORE_GETOPT_STORE_TRUE('p', "play", "Run in play mode."), 456 ECORE_GETOPT_STORE_TRUE('p', "play", "Run in play mode. Actions are executed and obtained "
432 ECORE_GETOPT_STORE_TRUE('i', "init", "Run in init mode."), 457 "screenshots are compared to the stored version (golden templates)."),
433 ECORE_GETOPT_STORE_TRUE('s', "simulation", "Run in simulation mode."), 458 ECORE_GETOPT_STORE_TRUE('i', "init", "Run in init mode. Actions are executed and obtained "
434 ECORE_GETOPT_STORE_TRUE(0, "scan-objects", "Extract information of all the objects at every shot."), 459 "screenshots are stored to be used as golden templates in the future."),
435 ECORE_GETOPT_STORE_TRUE(0, "disable-screenshots", "Disable screenshots."), 460 ECORE_GETOPT_STORE_TRUE('s', "simulation", "Run in simulation mode. Actions are executed and "
461 "displayed but no screenshot is obtained. Useful for debugging."),
462 ECORE_GETOPT_STORE_TRUE(0, "scan-objects", "Extract information of all the objects at every shot (UNUSED)."),
463 ECORE_GETOPT_STORE_TRUE(0, "disable-screenshots", "Disable screenshots. Only checks that actions "
464 "can be performed and the application does not crash."),
436 ECORE_GETOPT_STORE_STR('f', "fonts-dir", "Specify a directory of the fonts that should be used."), 465 ECORE_GETOPT_STORE_STR('f', "fonts-dir", "Specify a directory of the fonts that should be used."),
437 ECORE_GETOPT_STORE_TRUE(0, "stabilize-shots", "Wait for the frames to be stable before taking the shots."), 466 ECORE_GETOPT_STORE_TRUE(0, "stabilize-shots", "Wait for the frames to be stable before taking the shots."),
438 ECORE_GETOPT_COUNT('v', "verbose", "Turn verbose messages on."), 467 ECORE_GETOPT_COUNT('v', "verbose", "Turn verbose messages on."),
@@ -502,14 +531,14 @@ main(int argc, char *argv[])
502 } 531 }
503 else if (args == argc) 532 else if (args == argc)
504 { 533 {
505 fprintf(stderr, "Expected test list as the last argument..\n"); 534 fprintf(stderr, "Expected test list file as the last argument..\n");
506 ecore_getopt_help(stderr, &optdesc); 535 ecore_getopt_help(stderr, &optdesc);
507 ret = 1; 536 ret = 1;
508 goto end; 537 goto end;
509 } 538 }
510 else if (mode_play + mode_init + mode_simulation != 1) 539 else if (mode_play + mode_init + mode_simulation != 1)
511 { 540 {
512 fprintf(stderr, "At least and only one of the running modes can be set.\n"); 541 fprintf(stderr, "Exactly one running mode must be set.\n");
513 ecore_getopt_help(stderr, &optdesc); 542 ecore_getopt_help(stderr, &optdesc);
514 ret = 1; 543 ret = 1;
515 goto end; 544 goto end;
@@ -525,7 +554,7 @@ main(int argc, char *argv[])
525 554
526 if (!test_list) 555 if (!test_list)
527 { 556 {
528 fprintf(stderr, "No matching tests found in '%s'\n", list_file); 557 fprintf(stderr, "No matching tests found in list file '%s'\n", list_file);
529 ret = 1; 558 ret = 1;
530 goto end; 559 goto end;
531 } 560 }
@@ -533,7 +562,7 @@ main(int argc, char *argv[])
533 /* Pre-run summary */ 562 /* Pre-run summary */
534 fprintf(stderr, "Running with settings:\n"); 563 fprintf(stderr, "Running with settings:\n");
535 fprintf(stderr, "\tConcurrent jobs: %d\n", _max_jobs); 564 fprintf(stderr, "\tConcurrent jobs: %d\n", _max_jobs);
536 fprintf(stderr, "\tTest list: %s\n", list_file); 565 fprintf(stderr, "\tTest list file: %s\n", list_file);
537 fprintf(stderr, "\tBase dirs:\n"); 566 fprintf(stderr, "\tBase dirs:\n");
538 EINA_LIST_FOREACH(_base_dirs, itr, base_dir) 567 EINA_LIST_FOREACH(_base_dirs, itr, base_dir)
539 fprintf(stderr, "\t\t%s\n", base_dir); 568 fprintf(stderr, "\t\t%s\n", base_dir);
diff --git a/src/bin/exactness/exactness_play.in b/src/bin/exactness/exactness_play.in
index 650826f871..38200d9ba1 100644
--- a/src/bin/exactness/exactness_play.in
+++ b/src/bin/exactness/exactness_play.in
@@ -4,18 +4,23 @@ import argparse
4import subprocess 4import subprocess
5import os 5import os
6 6
7parser = argparse.ArgumentParser(description='A scenario recorder for EFL based applications.' 7parser = argparse.ArgumentParser(description='A recorded scenario player for EFL-based applications.\n\n'
8 '\tF1 - Request stabilization\n' 8 'Actions recorded with `exactness_record` can be played back with this\n'
9 '\tF2 - Request shot\n' 9 'application and screenshots obtained. It is typically more convenient to\n'
10 '\tF3 - Request to save the scenario\n') 10 'use the `exactness` wrapper in "play" mode to process files in batches.',
11parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here.', type=str, nargs='*') 11 formatter_class=argparse.RawDescriptionHelpFormatter,
12parser.add_argument('-o', '--output', metavar='output', help=" Set the destination for the shots.\n" 12 epilog='Example:\n'
13 " If a .exu is given, the shots are stored in the file.\n" 13 'exactness_play -s -t my_app.exu -- my_app --app --arguments')
14 " Otherwise the given path is considered as a directory\n" 14parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here. '
15 " where shots will be stored.\n" 15 'Use a -- if you need to provide arguments to the app.',
16 " If omitted, the output type (exu or dir) is determined\n" 16 type=str, nargs='*')
17 " by the given test extension (resp. exu or rec).", type=str) 17parser.add_argument('-o', '--output', metavar='output', help="Destination for the shots. "
18parser.add_argument('-t', '--tests', metavar='tests', help='Name of the filename where to store the test.', type=str) 18 "If a `.exu` file is given, the shots are stored in the file. "
19 "Otherwise the given path is considered as a directory "
20 "where shots will be stored. "
21 "If omitted, the output type (exu or dir) is determined "
22 "by the given test extension (resp. exu or rec).", type=str)
23parser.add_argument('-t', '--tests', metavar='tests', help='Name of the file where to store the test.', type=str)
19parser.add_argument('-s', '--show-on-screen', help='Show on screen', action='store_true', default=False) 24parser.add_argument('-s', '--show-on-screen', help='Show on screen', action='store_true', default=False)
20parser.add_argument('--scan-objects', help='Extract information of all the objects at every shot.', action='store_true') 25parser.add_argument('--scan-objects', help='Extract information of all the objects at every shot.', action='store_true')
21parser.add_argument('--external-injection', help='Expect events injection via Eina debug channel.', action='store_true') 26parser.add_argument('--external-injection', help='Expect events injection via Eina debug channel.', action='store_true')
@@ -24,9 +29,9 @@ parser.add_argument('-f', '--fontsdir', metavar='fontsdir', help='Specify a dire
24parser.add_argument('--stabilize-shots', help='Wait for the frames to be stable before taking the shots.', action='store_true') 29parser.add_argument('--stabilize-shots', help='Wait for the frames to be stable before taking the shots.', action='store_true')
25parser.add_argument('--speed', metavar='speed', help='Set the speed used to play the given test (default 1.0).', type=float, default=1.0) 30parser.add_argument('--speed', metavar='speed', help='Set the speed used to play the given test (default 1.0).', type=float, default=1.0)
26parser.add_argument('-v', '--verbose', help='Turn verbose messages on', action='store_true') 31parser.add_argument('-v', '--verbose', help='Turn verbose messages on', action='store_true')
27parser.add_argument('-L', '--license', help='the path where to find the meson build directory', action='store_true') 32parser.add_argument('-L', '--license', help='Print license information and exit.', action='store_true')
28parser.add_argument('-C', '--copyright', help='the path where to find the meson build directory', action='store_true') 33parser.add_argument('-C', '--copyright', help='Print copyright information and exit.', action='store_true')
29parser.add_argument('-V', '--version', help='the path where to find the meson build directory', action='store_true') 34parser.add_argument('-V', '--version', help='Print version information and exit.', action='store_true')
30 35
31G = parser.parse_args() 36G = parser.parse_args()
32 37
@@ -35,7 +40,7 @@ if G.license:
35 exit(0) 40 exit(0)
36 41
37if G.copyright: 42if G.copyright:
38 print("(C) 2017 Enlightenment.") 43 print("(C) 2017-2020 Enlightenment.")
39 exit(0) 44 exit(0)
40 45
41if G.version: 46if G.version:
diff --git a/src/bin/exactness/exactness_record.in b/src/bin/exactness/exactness_record.in
index 9c6d4cf4fd..377d465199 100644
--- a/src/bin/exactness/exactness_record.in
+++ b/src/bin/exactness/exactness_record.in
@@ -4,16 +4,31 @@ import argparse
4import subprocess 4import subprocess
5import os 5import os
6 6
7parser = argparse.ArgumentParser(description='A scenario recorder for EFL based applications.' 7parser = argparse.ArgumentParser(description='A scenario recorder for EFL-based applications.\n\n'
8 '\tF1 - Request stabilization\n' 8 'This records all actions the user performs on an EFL application (like keystrokes\n'
9 '\tF2 - Request shot\n' 9 'and mouse clicks) and stores them on a file.\n'
10 '\tF3 - Request to save the scenario\n') 10 'Later on, the `exactness` or `exactness_play` commands can be used to play\n'
11parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here.', type=str, nargs='*') 11 'back these actions and obtain screenshots.\n'
12parser.add_argument('-t', '--tests', metavar='tests', help='Name of the filename where to store the test.', type=str) 12 '\n'
13parser.add_argument('-f', '--fontsdir', metavar='fontsdir', help='Specify a directory of the fonts that should be used.', type=str) 13 'While running this application, use the following keys to control the process:\n'
14parser.add_argument('-L', '--license', help='the path where to find the meson build directory', action='store_true') 14 '\tF1 - Request stabilization.\n'
15parser.add_argument('-C', '--copyright', help='the path where to find the meson build directory', action='store_true') 15 '\tF2 - Request screenshot.\n'
16parser.add_argument('-V', '--version', help='the path where to find the meson build directory', action='store_true') 16 '\tF3 - Request to save the scenario.\n'
17 '\n'
18 'Note: If you don\'t press F3 at least once, no output file will be generated.',
19 formatter_class=argparse.RawDescriptionHelpFormatter,
20 epilog='Example:\n'
21 'exactness_record -t my_app.exu -- my_app --app --arguments')
22parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here. '
23 'Use a -- if you need to provide arguments to the app.',
24 type=str, nargs='*')
25parser.add_argument('-t', '--tests', metavar='tests', help='Name of the file where to store the test. '
26 'It is recommended to use the `.exu` extension.', type=str)
27parser.add_argument('-f', '--fontsdir', metavar='fontsdir', help='Directory of the fonts that should be used.',
28 type=str)
29parser.add_argument('-L', '--license', help='Print license information and exit.', action='store_true')
30parser.add_argument('-C', '--copyright', help='Print copyright information and exit.', action='store_true')
31parser.add_argument('-V', '--version', help='Print version information and exit.', action='store_true')
17 32
18G = parser.parse_args() 33G = parser.parse_args()
19 34
@@ -22,7 +37,7 @@ if G.license:
22 exit(0) 37 exit(0)
23 38
24if G.copyright: 39if G.copyright:
25 print("(C) 2017 Enlightenment.") 40 print("(C) 2017-2020 Enlightenment.")
26 exit(0) 41 exit(0)
27 42
28if G.version: 43if G.version:
diff --git a/src/bin/exactness/inspect.c b/src/bin/exactness/inspect.c
index 68da3548a3..1e1dc48018 100644
--- a/src/bin/exactness/inspect.c
+++ b/src/bin/exactness/inspect.c
@@ -1239,9 +1239,12 @@ static const Ecore_Getopt optdesc = {
1239 "exactness_inspect", 1239 "exactness_inspect",
1240 "%prog [options] [<exu file> | <file1 file2>]", 1240 "%prog [options] [<exu file> | <file1 file2>]",
1241 NULL, 1241 NULL,
1242 "(C) 2016 Enlightenment", 1242 "(C) 2016-2020 Enlightenment",
1243 "BSD", 1243 "BSD",
1244 "Inspector for Exactness", 1244 "Inspector for Exactness\n"
1245 "\n"
1246 "Dumps the contents of `.exu` files obtained with `exactness_record` or"
1247 "`exactness -i` in an easy-to-examine way.",
1245 0, 1248 0,
1246 { 1249 {
1247 ECORE_GETOPT_STORE_USHORT('d', "delay", "Delay the given recording by a given time (in milliseconds)."), 1250 ECORE_GETOPT_STORE_USHORT('d', "delay", "Delay the given recording by a given time (in milliseconds)."),