From: Xavi Artigas Date: Wed, 1 Apr 2020 16:40:40 +0000 (+0200) Subject: exactness docs: Add docs, fix docs, remove docs X-Git-Tag: submit/tizen/20200405.220557~34 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=8032178129ae852589382519586915eef47fdf55;p=platform%2Fupstream%2Fefl.git 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 --- diff --git a/src/bin/exactness/exactness.c b/src/bin/exactness/exactness.c index 6599ef7..c99fcee 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) static const Ecore_Getopt optdesc = { "exactness", - "%prog [options] <-r|-p|-i|-s> ", + "%prog [options] <-p|-i|-s> ", PACKAGE_VERSION, - "(C) 2013 Enlightenment", + "(C) 2013-2020 Enlightenment", "BSD", - "A pixel perfect test suite for EFL based applications.", + "A pixel-perfect test suite for EFL-based applications.\n" + "\n" + "This binary allows running the individual tools `exactness_record` and\n" + "`exactness_play` in batch for a set of tests specified in a test list file.\n" + "\n" + "To obtain the reference templates (the \"golden\" files):\n" + "1.For each tested application, run `exactness_record` to launch the\n" + " application and record actions like keystrokes and mouse clicks.\n" + " This produces a test file with `.exu` extension.\n" + "2.Run `exactness` in init mode (-i) to execute the stored actions in all\n" + " the tests in the test list file and obtain screenshots.\n" + " The screenshots are embedded into the test `.exu` file.\n" + "\n" + "To check if the application currently matches the reference templates:\n" + "1.Run `exactness` in play mode (-p) to execute the stored actions in all\n" + " the tests in the test list file and compare the obtained screenshots\n" + " with the stored versions (the reference templates).\n" + " If mismatches are detected an error report is produced, including\n" + " a graphical diff of the screenshots.\n" + "\n" + "The test list file contains one line per test. Each line starts with the\n" + "test file name (without the `.exu` extension), a space and then the command\n" + "to execute, including parameters if any. # indicates a comment.\n" + "Example:\n" + "separator elementary_test -to Separator", 0, { - ECORE_GETOPT_APPEND('b', "base-dir", "The location of the exu files.", ECORE_GETOPT_TYPE_STR), - ECORE_GETOPT_STORE_STR('o', "output", "The location of the images."), + ECORE_GETOPT_APPEND('b', "base-dir", "The location of the exu files. Defaults to `./recordings/`.", + ECORE_GETOPT_TYPE_STR), + ECORE_GETOPT_STORE_STR('o', "output", "The location of the images. Defaults to `./`."), ECORE_GETOPT_STORE_STR('w', "wrap", "Use a custom command to launch the tests (e.g valgrind)."), - ECORE_GETOPT_STORE_USHORT('j', "jobs", "The number of jobs to run in parallel."), - ECORE_GETOPT_STORE_TRUE('p', "play", "Run in play mode."), - ECORE_GETOPT_STORE_TRUE('i', "init", "Run in init mode."), - ECORE_GETOPT_STORE_TRUE('s', "simulation", "Run in simulation mode."), - ECORE_GETOPT_STORE_TRUE(0, "scan-objects", "Extract information of all the objects at every shot."), - ECORE_GETOPT_STORE_TRUE(0, "disable-screenshots", "Disable screenshots."), + ECORE_GETOPT_STORE_USHORT('j', "jobs", "The number of jobs to run in parallel. Defaults to 1."), + ECORE_GETOPT_STORE_TRUE('p', "play", "Run in play mode. Actions are executed and obtained " + "screenshots are compared to the stored version (golden templates)."), + ECORE_GETOPT_STORE_TRUE('i', "init", "Run in init mode. Actions are executed and obtained " + "screenshots are stored to be used as golden templates in the future."), + ECORE_GETOPT_STORE_TRUE('s', "simulation", "Run in simulation mode. Actions are executed and " + "displayed but no screenshot is obtained. Useful for debugging."), + ECORE_GETOPT_STORE_TRUE(0, "scan-objects", "Extract information of all the objects at every shot (UNUSED)."), + ECORE_GETOPT_STORE_TRUE(0, "disable-screenshots", "Disable screenshots. Only checks that actions " + "can be performed and the application does not crash."), ECORE_GETOPT_STORE_STR('f', "fonts-dir", "Specify a directory of the fonts that should be used."), ECORE_GETOPT_STORE_TRUE(0, "stabilize-shots", "Wait for the frames to be stable before taking the shots."), ECORE_GETOPT_COUNT('v', "verbose", "Turn verbose messages on."), @@ -502,14 +531,14 @@ main(int argc, char *argv[]) } else if (args == argc) { - fprintf(stderr, "Expected test list as the last argument..\n"); + fprintf(stderr, "Expected test list file as the last argument..\n"); ecore_getopt_help(stderr, &optdesc); ret = 1; goto end; } else if (mode_play + mode_init + mode_simulation != 1) { - fprintf(stderr, "At least and only one of the running modes can be set.\n"); + fprintf(stderr, "Exactly one running mode must be set.\n"); ecore_getopt_help(stderr, &optdesc); ret = 1; goto end; @@ -525,7 +554,7 @@ main(int argc, char *argv[]) if (!test_list) { - fprintf(stderr, "No matching tests found in '%s'\n", list_file); + fprintf(stderr, "No matching tests found in list file '%s'\n", list_file); ret = 1; goto end; } @@ -533,7 +562,7 @@ main(int argc, char *argv[]) /* Pre-run summary */ fprintf(stderr, "Running with settings:\n"); fprintf(stderr, "\tConcurrent jobs: %d\n", _max_jobs); - fprintf(stderr, "\tTest list: %s\n", list_file); + fprintf(stderr, "\tTest list file: %s\n", list_file); fprintf(stderr, "\tBase dirs:\n"); EINA_LIST_FOREACH(_base_dirs, itr, base_dir) 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 650826f..38200d9 100644 --- a/src/bin/exactness/exactness_play.in +++ b/src/bin/exactness/exactness_play.in @@ -4,18 +4,23 @@ import argparse import subprocess import os -parser = argparse.ArgumentParser(description='A scenario recorder for EFL based applications.' - '\tF1 - Request stabilization\n' - '\tF2 - Request shot\n' - '\tF3 - Request to save the scenario\n') -parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here.', type=str, nargs='*') -parser.add_argument('-o', '--output', metavar='output', help=" Set the destination for the shots.\n" - " If a .exu is given, the shots are stored in the file.\n" - " Otherwise the given path is considered as a directory\n" - " where shots will be stored.\n" - " If omitted, the output type (exu or dir) is determined\n" - " by the given test extension (resp. exu or rec).", type=str) -parser.add_argument('-t', '--tests', metavar='tests', help='Name of the filename where to store the test.', type=str) +parser = argparse.ArgumentParser(description='A recorded scenario player for EFL-based applications.\n\n' + 'Actions recorded with `exactness_record` can be played back with this\n' + 'application and screenshots obtained. It is typically more convenient to\n' + 'use the `exactness` wrapper in "play" mode to process files in batches.', + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog='Example:\n' + 'exactness_play -s -t my_app.exu -- my_app --app --arguments') +parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here. ' + 'Use a -- if you need to provide arguments to the app.', + type=str, nargs='*') +parser.add_argument('-o', '--output', metavar='output', help="Destination for the shots. " + "If a `.exu` file is given, the shots are stored in the file. " + "Otherwise the given path is considered as a directory " + "where shots will be stored. " + "If omitted, the output type (exu or dir) is determined " + "by the given test extension (resp. exu or rec).", type=str) +parser.add_argument('-t', '--tests', metavar='tests', help='Name of the file where to store the test.', type=str) parser.add_argument('-s', '--show-on-screen', help='Show on screen', action='store_true', default=False) parser.add_argument('--scan-objects', help='Extract information of all the objects at every shot.', action='store_true') parser.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 parser.add_argument('--stabilize-shots', help='Wait for the frames to be stable before taking the shots.', action='store_true') parser.add_argument('--speed', metavar='speed', help='Set the speed used to play the given test (default 1.0).', type=float, default=1.0) parser.add_argument('-v', '--verbose', help='Turn verbose messages on', action='store_true') -parser.add_argument('-L', '--license', help='the path where to find the meson build directory', action='store_true') -parser.add_argument('-C', '--copyright', help='the path where to find the meson build directory', action='store_true') -parser.add_argument('-V', '--version', help='the path where to find the meson build directory', action='store_true') +parser.add_argument('-L', '--license', help='Print license information and exit.', action='store_true') +parser.add_argument('-C', '--copyright', help='Print copyright information and exit.', action='store_true') +parser.add_argument('-V', '--version', help='Print version information and exit.', action='store_true') G = parser.parse_args() @@ -35,7 +40,7 @@ if G.license: exit(0) if G.copyright: - print("(C) 2017 Enlightenment.") + print("(C) 2017-2020 Enlightenment.") exit(0) if G.version: diff --git a/src/bin/exactness/exactness_record.in b/src/bin/exactness/exactness_record.in index 9c6d4cf..377d465 100644 --- a/src/bin/exactness/exactness_record.in +++ b/src/bin/exactness/exactness_record.in @@ -4,16 +4,31 @@ import argparse import subprocess import os -parser = argparse.ArgumentParser(description='A scenario recorder for EFL based applications.' - '\tF1 - Request stabilization\n' - '\tF2 - Request shot\n' - '\tF3 - Request to save the scenario\n') -parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here.', type=str, nargs='*') -parser.add_argument('-t', '--tests', metavar='tests', help='Name of the filename where to store the test.', type=str) -parser.add_argument('-f', '--fontsdir', metavar='fontsdir', help='Specify a directory of the fonts that should be used.', type=str) -parser.add_argument('-L', '--license', help='the path where to find the meson build directory', action='store_true') -parser.add_argument('-C', '--copyright', help='the path where to find the meson build directory', action='store_true') -parser.add_argument('-V', '--version', help='the path where to find the meson build directory', action='store_true') +parser = argparse.ArgumentParser(description='A scenario recorder for EFL-based applications.\n\n' + 'This records all actions the user performs on an EFL application (like keystrokes\n' + 'and mouse clicks) and stores them on a file.\n' + 'Later on, the `exactness` or `exactness_play` commands can be used to play\n' + 'back these actions and obtain screenshots.\n' + '\n' + 'While running this application, use the following keys to control the process:\n' + '\tF1 - Request stabilization.\n' + '\tF2 - Request screenshot.\n' + '\tF3 - Request to save the scenario.\n' + '\n' + 'Note: If you don\'t press F3 at least once, no output file will be generated.', + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog='Example:\n' + 'exactness_record -t my_app.exu -- my_app --app --arguments') +parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here. ' + 'Use a -- if you need to provide arguments to the app.', + type=str, nargs='*') +parser.add_argument('-t', '--tests', metavar='tests', help='Name of the file where to store the test. ' + 'It is recommended to use the `.exu` extension.', type=str) +parser.add_argument('-f', '--fontsdir', metavar='fontsdir', help='Directory of the fonts that should be used.', + type=str) +parser.add_argument('-L', '--license', help='Print license information and exit.', action='store_true') +parser.add_argument('-C', '--copyright', help='Print copyright information and exit.', action='store_true') +parser.add_argument('-V', '--version', help='Print version information and exit.', action='store_true') G = parser.parse_args() @@ -22,7 +37,7 @@ if G.license: exit(0) if G.copyright: - print("(C) 2017 Enlightenment.") + print("(C) 2017-2020 Enlightenment.") exit(0) if G.version: diff --git a/src/bin/exactness/inspect.c b/src/bin/exactness/inspect.c index 68da354..1e1dc48 100644 --- a/src/bin/exactness/inspect.c +++ b/src/bin/exactness/inspect.c @@ -1239,9 +1239,12 @@ static const Ecore_Getopt optdesc = { "exactness_inspect", "%prog [options] [ | ]", NULL, - "(C) 2016 Enlightenment", + "(C) 2016-2020 Enlightenment", "BSD", - "Inspector for Exactness", + "Inspector for Exactness\n" + "\n" + "Dumps the contents of `.exu` files obtained with `exactness_record` or" + "`exactness -i` in an easy-to-examine way.", 0, { ECORE_GETOPT_STORE_USHORT('d', "delay", "Delay the given recording by a given time (in milliseconds)."),