1#!/usr/bin/env python
2#
3# Copyright 2018, The Android Open Source Project
4#
5# Licensed under the Apache License, Version 2.0 (the "License");
6# you may not use this file except in compliance with the License.
7# You may obtain a copy of the License at
8#
9#     http://www.apache.org/licenses/LICENSE-2.0
10#
11# Unless required by applicable law or agreed to in writing, software
12# distributed under the License is distributed on an "AS IS" BASIS,
13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14# See the License for the specific language governing permissions and
15# limitations under the License.
16
17"""
18Atest Argument Parser class for atest.
19"""
20
21# pylint: disable=line-too-long
22
23import argparse
24import pydoc
25
26import atest_utils
27import constants
28
29# Constants used for AtestArgParser and EPILOG_TEMPLATE
30HELP_DESC = ('A command line tool that allows users to build, install, and run '
31             'Android tests locally, greatly speeding test re-runs without '
32             'requiring knowledge of Trade Federation test harness command line'
33             ' options.')
34
35# Constants used for arg help message(sorted in alphabetic)
36ALL_ABI = 'Set to run tests for all abis.'
37BUILD = 'Run a build.'
38CLEAR_CACHE = 'Wipe out the test_infos cache of the test.'
39COLLECT_TESTS_ONLY = ('Collect a list test cases of the instrumentation tests '
40                      'without testing them in real.')
41DISABLE_TEARDOWN = 'Disable test teardown and cleanup.'
42DRY_RUN = 'Dry run atest without building, installing and running tests in real.'
43ENABLE_FILE_PATTERNS = 'Enable FILE_PATTERNS in TEST_MAPPING.'
44HISTORY = ('Show test results in chronological order(with specified number or '
45           'all by default).')
46HOST = ('Run the test completely on the host without a device. '
47        '(Note: running a host test that requires a device without '
48        '--host will fail.)')
49INCLUDE_SUBDIRS = 'Search TEST_MAPPING files in subdirs as well.'
50INFO = 'Show module information.'
51INSTALL = 'Install an APK.'
52INSTANT = ('Run the instant_app version of the module if the module supports it. '
53           'Note: Nothing\'s going to run if it\'s not an Instant App test and '
54           '"--instant" is passed.')
55ITERATION = 'Loop-run tests until the max iteration is reached. (10 by default)'
56LATEST_RESULT = 'Print latest test result.'
57LIST_MODULES = 'List testable modules for the given suite.'
58REBUILD_MODULE_INFO = ('Forces a rebuild of the module-info.json file. '
59                       'This may be necessary following a repo sync or '
60                       'when writing a new test.')
61RERUN_UNTIL_FAILURE = ('Rerun all tests until a failure occurs or the max '
62                       'iteration is reached. (10 by default)')
63RETRY_ANY_FAILURE = ('Rerun failed tests until passed or the max iteration '
64                     'is reached. (10 by default)')
65SERIAL = 'The device to run the test on.'
66SHARDING = 'Option to specify sharding count. The default value is 2'
67TEST = ('Run the tests. WARNING: Many test configs force cleanup of device '
68        'after test run. In this case, "-d" must be used in previous test run to '
69        'disable cleanup for "-t" to work. Otherwise, device will need to be '
70        'setup again with "-i".')
71TEST_MAPPING = 'Run tests defined in TEST_MAPPING files.'
72TF_TEMPLATE = ('Add extra tradefed template for ATest suite, '
73               'e.g. atest <test> --tf-template <template_key>=<template_path>')
74TF_DEBUG = 'Enable tradefed debug mode with a specify port. Default value is 10888.'
75UPDATE_CMD_MAPPING = ('Update the test command of input tests. Warning: result '
76                      'will be saved under tools/tradefederation/core/atest/test_data.')
77USER_TYPE = 'Run test with specific user type, e.g. atest <test> --user-type secondary_user'
78VERBOSE = 'Display DEBUG level logging.'
79VERIFY_CMD_MAPPING = 'Verify the test command of input tests.'
80VERSION = 'Display version string.'
81WAIT_FOR_DEBUGGER = 'Wait for debugger prior to execution (Instrumentation tests only).'
82
83def _positive_int(value):
84    """Verify value by whether or not a positive integer.
85
86    Args:
87        value: A string of a command-line argument.
88
89    Returns:
90        int of value, if it is an positive integer.
91        Otherwise, raise argparse.ArgumentTypeError.
92    """
93    err_msg = "invalid positive int value: '%s'" % value
94    try:
95        converted_value = int(value)
96        if converted_value < 1:
97            raise argparse.ArgumentTypeError(err_msg)
98        return converted_value
99    except ValueError:
100        raise argparse.ArgumentTypeError(err_msg)
101
102class AtestArgParser(argparse.ArgumentParser):
103    """Atest wrapper of ArgumentParser."""
104
105    def __init__(self):
106        """Initialise an ArgumentParser instance."""
107        atest_utils.print_data_collection_notice()
108        super(AtestArgParser, self).__init__(
109            description=HELP_DESC, add_help=False)
110
111    def add_atest_args(self):
112        """A function that does ArgumentParser.add_argument()"""
113        self.add_argument('tests', nargs='*', help='Tests to build and/or run.')
114        # Options that to do with testing.
115        self.add_argument('-a', '--all-abi', action='store_true', help=ALL_ABI)
116        self.add_argument('-b', '--build', action='append_const', dest='steps',
117                          const=constants.BUILD_STEP, help=BUILD)
118        self.add_argument('-d', '--disable-teardown', action='store_true',
119                          help=DISABLE_TEARDOWN)
120        self.add_argument('--host', action='store_true', help=HOST)
121        self.add_argument('-i', '--install', action='append_const',
122                          dest='steps', const=constants.INSTALL_STEP,
123                          help=INSTALL)
124        self.add_argument('-m', constants.REBUILD_MODULE_INFO_FLAG,
125                          action='store_true', help=REBUILD_MODULE_INFO)
126        self.add_argument('-s', '--serial', help=SERIAL)
127        self.add_argument('--sharding', nargs='?', const=2,
128                          type=_positive_int, default=0,
129                          help=SHARDING)
130        self.add_argument('-t', '--test', action='append_const', dest='steps',
131                          const=constants.TEST_STEP, help=TEST)
132        self.add_argument('-w', '--wait-for-debugger', action='store_true',
133                          help=WAIT_FOR_DEBUGGER)
134
135        # Options related to Test Mapping
136        self.add_argument('-p', '--test-mapping', action='store_true',
137                          help=TEST_MAPPING)
138        self.add_argument('--include-subdirs', action='store_true',
139                          help=INCLUDE_SUBDIRS)
140        # TODO(146980564): Remove enable-file-patterns when support
141        # file-patterns in TEST_MAPPING by default.
142        self.add_argument('--enable-file-patterns', action='store_true',
143                          help=ENABLE_FILE_PATTERNS)
144
145        # Options for information queries and dry-runs:
146        # A group of options for dry-runs. They are mutually exclusive
147        # in a command line.
148        group = self.add_mutually_exclusive_group()
149        group.add_argument('--collect-tests-only', action='store_true',
150                           help=COLLECT_TESTS_ONLY)
151        group.add_argument('--dry-run', action='store_true', help=DRY_RUN)
152        self.add_argument('-h', '--help', action='store_true',
153                          help='Print this help message.')
154        self.add_argument('--info', action='store_true', help=INFO)
155        self.add_argument('-L', '--list-modules', help=LIST_MODULES)
156        self.add_argument('-v', '--verbose', action='store_true', help=VERBOSE)
157        self.add_argument('-V', '--version', action='store_true', help=VERSION)
158
159        # Obsolete options that will be removed soon.
160        self.add_argument('--generate-baseline', nargs='?',
161                          type=int, const=5, default=0,
162                          help='Generate baseline metrics, run 5 iterations by'
163                               'default. Provide an int argument to specify '
164                               '# iterations.')
165        self.add_argument('--generate-new-metrics', nargs='?',
166                          type=int, const=5, default=0,
167                          help='Generate new metrics, run 5 iterations by '
168                               'default. Provide an int argument to specify '
169                               '# iterations.')
170        self.add_argument('--detect-regression', nargs='*',
171                          help='Run regression detection algorithm. Supply '
172                               'path to baseline and/or new metrics folders.')
173
174        # Options related to module parameterization
175        self.add_argument('--instant', action='store_true', help=INSTANT)
176        self.add_argument('--user-type', help=USER_TYPE)
177
178        # Option for dry-run command mapping result and cleaning cache.
179        self.add_argument('-c', '--clear-cache', action='store_true',
180                          help=CLEAR_CACHE)
181        self.add_argument('-u', '--update-cmd-mapping', action='store_true',
182                          help=UPDATE_CMD_MAPPING)
183        self.add_argument('-y', '--verify-cmd-mapping', action='store_true',
184                          help=VERIFY_CMD_MAPPING)
185
186        # Options for Tradefed debug mode.
187        self.add_argument('-D', '--tf-debug', nargs='?', const=10888,
188                          type=_positive_int, default=0,
189                          help=TF_DEBUG)
190
191        # Options for Tradefed customization related.
192        self.add_argument('--tf-template', action='append',
193                          help=TF_TEMPLATE)
194
195        # A group of options for rerun strategy. They are mutually exclusive
196        # in a command line.
197        group = self.add_mutually_exclusive_group()
198        # Option for rerun tests for the specified number iterations.
199        group.add_argument('--iterations', nargs='?',
200                           type=_positive_int, const=10, default=0,
201                           metavar='MAX_ITERATIONS', help=ITERATION)
202        group.add_argument('--rerun-until-failure', nargs='?',
203                           type=_positive_int, const=10, default=0,
204                           metavar='MAX_ITERATIONS', help=RERUN_UNTIL_FAILURE)
205        group.add_argument('--retry-any-failure', nargs='?',
206                           type=_positive_int, const=10, default=0,
207                           metavar='MAX_ITERATIONS', help=RETRY_ANY_FAILURE)
208
209        # A group of options for history. They are mutually exclusive
210        # in a command line.
211        history_group = self.add_mutually_exclusive_group()
212        # History related options.
213        history_group.add_argument('--latest-result', action='store_true',
214                                   help=LATEST_RESULT)
215        history_group.add_argument('--history', nargs='?', const='99999',
216                                   help=HISTORY)
217
218        # This arg actually doesn't consume anything, it's primarily used for
219        # the help description and creating custom_args in the NameSpace object.
220        self.add_argument('--', dest='custom_args', nargs='*',
221                          help='Specify custom args for the test runners. '
222                               'Everything after -- will be consumed as '
223                               'custom args.')
224
225    def get_args(self):
226        """This method is to get args from actions and return optional args.
227
228        Returns:
229            A list of optional arguments.
230        """
231        argument_list = []
232        # The output of _get_optional_actions(): [['-t', '--test'], [--info]]
233        # return an argument list: ['-t', '--test', '--info']
234        for arg in self._get_optional_actions():
235            argument_list.extend(arg.option_strings)
236        return argument_list
237
238
239def print_epilog_text():
240    """Pagination print EPILOG_TEXT.
241
242    Returns:
243        STDOUT from pydoc.pager().
244    """
245    epilog_text = EPILOG_TEMPLATE.format(ALL_ABI=ALL_ABI,
246                                         BUILD=BUILD,
247                                         CLEAR_CACHE=CLEAR_CACHE,
248                                         COLLECT_TESTS_ONLY=COLLECT_TESTS_ONLY,
249                                         DISABLE_TEARDOWN=DISABLE_TEARDOWN,
250                                         DRY_RUN=DRY_RUN,
251                                         ENABLE_FILE_PATTERNS=ENABLE_FILE_PATTERNS,
252                                         HELP_DESC=HELP_DESC,
253                                         HISTORY=HISTORY,
254                                         HOST=HOST,
255                                         INCLUDE_SUBDIRS=INCLUDE_SUBDIRS,
256                                         INFO=INFO,
257                                         INSTALL=INSTALL,
258                                         INSTANT=INSTANT,
259                                         ITERATION=ITERATION,
260                                         LATEST_RESULT=LATEST_RESULT,
261                                         LIST_MODULES=LIST_MODULES,
262                                         REBUILD_MODULE_INFO=REBUILD_MODULE_INFO,
263                                         RERUN_UNTIL_FAILURE=RERUN_UNTIL_FAILURE,
264                                         RETRY_ANY_FAILURE=RETRY_ANY_FAILURE,
265                                         SERIAL=SERIAL,
266                                         SHARDING=SHARDING,
267                                         TEST=TEST,
268                                         TEST_MAPPING=TEST_MAPPING,
269                                         TF_DEBUG=TF_DEBUG,
270                                         TF_TEMPLATE=TF_TEMPLATE,
271                                         USER_TYPE=USER_TYPE,
272                                         UPDATE_CMD_MAPPING=UPDATE_CMD_MAPPING,
273                                         VERBOSE=VERBOSE,
274                                         VERSION=VERSION,
275                                         VERIFY_CMD_MAPPING=VERIFY_CMD_MAPPING,
276                                         WAIT_FOR_DEBUGGER=WAIT_FOR_DEBUGGER)
277    return pydoc.pager(epilog_text)
278
279
280EPILOG_TEMPLATE = r'''ATEST(1)                       ASuite/ATest
281
282NAME
283        atest - {HELP_DESC}
284
285
286SYNOPSIS
287        atest [OPTION]... [TEST_TARGET]... -- [CUSTOM_ARGS]...
288
289
290OPTIONS
291        Below arguments are catagorised by features and purposes. Arguments marked with default will apply even the user does not pass it explicitly.
292
293        [ Testing ]
294        -a, --all-abi
295            {ALL_ABI}
296
297        -b, --build:
298            {BUILD} (default)
299
300        -d, --disable-teardown
301            {DISABLE_TEARDOWN}
302
303        -D --tf-debug
304            {TF_DEBUG}
305
306        --history
307            {HISTORY}
308
309        --host
310            {HOST}
311
312        -i, --install
313            {INSTALL} (default)
314
315        -m, --rebuild-module-info
316            {REBUILD_MODULE_INFO} (default)
317
318        -s, --serial
319            {SERIAL}
320
321        --sharding
322          {SHARDING}
323
324        -t, --test
325            {TEST} (default)
326
327        --tf-template
328            {TF_TEMPLATE}
329
330        -w, --wait-for-debugger
331            {WAIT_FOR_DEBUGGER}
332
333
334        [ Test Mapping ]
335        -p, --test-mapping
336            {TEST_MAPPING}
337
338        --include-subdirs
339            {INCLUDE_SUBDIRS}
340
341        --enable-file-patterns
342            {ENABLE_FILE_PATTERNS}
343
344
345        [ Information/Queries ]
346        --collect-tests-only
347            {COLLECT_TESTS_ONLY}
348
349        --info
350            {INFO}
351
352        -L, --list-modules
353            {LIST_MODULES}
354
355        --latest-result
356            {LATEST_RESULT}
357
358        -v, --verbose
359            {VERBOSE}
360
361        -V, --version
362            {VERSION}
363
364
365        [ Dry-Run and Caching ]
366        --dry-run
367            {DRY_RUN}
368
369        -c, --clear-cache
370            {CLEAR_CACHE}
371
372        -u, --update-cmd-mapping
373            {UPDATE_CMD_MAPPING}
374
375        -y, --verify-cmd-mapping
376            {VERIFY_CMD_MAPPING}
377
378
379        [ Module Parameterization ]
380        --instant
381            {INSTANT}
382
383        --user-type
384            {USER_TYPE}
385
386
387        [ Iteration Testing ]
388        --iterations
389            {ITERATION}
390
391        --rerun-until-failure
392            {RERUN_UNTIL_FAILURE}
393
394        --retry-any-failure
395            {RETRY_ANY_FAILURE}
396
397
398EXAMPLES
399    - - - - - - - - -
400    IDENTIFYING TESTS
401    - - - - - - - - -
402
403    The positional argument <tests> should be a reference to one or more of the tests you'd like to run. Multiple tests can be run in one command by separating test references with spaces.
404
405    Usage template: atest <reference_to_test_1> <reference_to_test_2>
406
407    A <reference_to_test> can be satisfied by the test's MODULE NAME, MODULE:CLASS, CLASS NAME, TF INTEGRATION TEST, FILE PATH or PACKAGE NAME. Explanations and examples of each follow.
408
409
410    < MODULE NAME >
411
412        Identifying a test by its module name will run the entire module. Input the name as it appears in the LOCAL_MODULE or LOCAL_PACKAGE_NAME variables in that test's Android.mk or Android.bp file.
413
414        Note: Use < TF INTEGRATION TEST > to run non-module tests integrated directly into TradeFed.
415
416        Examples:
417            atest FrameworksServicesTests
418            atest CtsJankDeviceTestCases
419
420
421    < MODULE:CLASS >
422
423        Identifying a test by its class name will run just the tests in that class and not the whole module. MODULE:CLASS is the preferred way to run a single class. MODULE is the same as described above. CLASS is the name of the test class in the .java file. It can either be the fully qualified class name or just the basic name.
424
425        Examples:
426            atest FrameworksServicesTests:ScreenDecorWindowTests
427            atest FrameworksServicesTests:com.android.server.wm.ScreenDecorWindowTests
428            atest CtsJankDeviceTestCases:CtsDeviceJankUi
429
430
431    < CLASS NAME >
432
433        A single class can also be run by referencing the class name without the module name.
434
435        Examples:
436            atest ScreenDecorWindowTests
437            atest CtsDeviceJankUi
438
439        However, this will take more time than the equivalent MODULE:CLASS reference, so we suggest using a MODULE:CLASS reference whenever possible. Examples below are ordered by performance from the fastest to the slowest:
440
441        Examples:
442            atest FrameworksServicesTests:com.android.server.wm.ScreenDecorWindowTests
443            atest FrameworksServicesTests:ScreenDecorWindowTests
444            atest ScreenDecorWindowTests
445
446    < TF INTEGRATION TEST >
447
448        To run tests that are integrated directly into TradeFed (non-modules), input the name as it appears in the output of the "tradefed.sh list configs" cmd.
449
450        Examples:
451           atest example/reboot
452           atest native-benchmark
453
454
455    < FILE PATH >
456
457        Both module-based tests and integration-based tests can be run by inputting the path to their test file or dir as appropriate. A single class can also be run by inputting the path to the class's java file.
458
459        Both relative and absolute paths are supported.
460
461        Example - 2 ways to run the `CtsJankDeviceTestCases` module via path:
462        1. run module from android <repo root>:
463            atest cts/tests/jank/jank
464
465        2. from <android root>/cts/tests/jank:
466            atest .
467
468        Example - run a specific class within CtsJankDeviceTestCases module from <android repo> root via path:
469           atest cts/tests/jank/src/android/jank/cts/ui/CtsDeviceJankUi.java
470
471        Example - run an integration test from <android repo> root via path:
472           atest tools/tradefederation/contrib/res/config/example/reboot.xml
473
474
475    < PACKAGE NAME >
476
477        Atest supports searching tests from package name as well.
478
479        Examples:
480           atest com.android.server.wm
481           atest android.jank.cts
482
483
484    - - - - - - - - - - - - - - - - - - - - - - - - - -
485    SPECIFYING INDIVIDUAL STEPS: BUILD, INSTALL OR RUN
486    - - - - - - - - - - - - - - - - - - - - - - - - - -
487
488    The -b, -i and -t options allow you to specify which steps you want to run. If none of those options are given, then all steps are run. If any of these options are provided then only the listed steps are run.
489
490    Note: -i alone is not currently support and can only be included with -t.
491    Both -b and -t can be run alone.
492
493    Examples:
494        atest -b <test>    (just build targets)
495        atest -t <test>    (run tests only)
496        atest -it <test>   (install apk and run tests)
497        atest -bt <test>   (build targets, run tests, but skip installing apk)
498
499
500    Atest now has the ability to force a test to skip its cleanup/teardown step. Many tests, e.g. CTS, cleanup the device after the test is run, so trying to rerun your test with -t will fail without having the --disable-teardown parameter. Use -d before -t to skip the test clean up step and test iteratively.
501
502        atest -d <test>    (disable installing apk and cleanning up device)
503        atest -t <test>
504
505    Note that -t disables both setup/install and teardown/cleanup of the device. So you can continue to rerun your test with just
506
507        atest -t <test>
508
509    as many times as you want.
510
511
512    - - - - - - - - - - - - -
513    RUNNING SPECIFIC METHODS
514    - - - - - - - - - - - - -
515
516    It is possible to run only specific methods within a test class. To run only specific methods, identify the class in any of the ways supported for identifying a class (MODULE:CLASS, FILE PATH, etc) and then append the name of the method or method using the following template:
517
518      <reference_to_class>#<method1>
519
520    Multiple methods can be specified with commas:
521
522      <reference_to_class>#<method1>,<method2>,<method3>...
523
524    Examples:
525      atest com.android.server.wm.ScreenDecorWindowTests#testMultipleDecors
526
527      atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval
528
529
530    - - - - - - - - - - - - -
531    RUNNING MULTIPLE CLASSES
532    - - - - - - - - - - - - -
533
534    To run multiple classes, deliminate them with spaces just like you would when running multiple tests.  Atest will handle building and running classes in the most efficient way possible, so specifying a subset of classes in a module will improve performance over running the whole module.
535
536
537    Examples:
538    - two classes in same module:
539      atest FrameworksServicesTests:ScreenDecorWindowTests FrameworksServicesTests:DimmerTests
540
541    - two classes, different modules:
542      atest FrameworksServicesTests:ScreenDecorWindowTests CtsJankDeviceTestCases:CtsDeviceJankUi
543
544
545    - - - - - - - - - - -
546    RUNNING NATIVE TESTS
547    - - - - - - - - - - -
548
549    Atest can run native test.
550
551    Example:
552    - Input tests:
553      atest -a libinput_tests inputflinger_tests
554
555    Use -a|--all-abi to run the tests for all available device architectures, which in this example is armeabi-v7a (ARM 32-bit) and arm64-v8a (ARM 64-bit).
556
557    To select a specific native test to run, use colon (:) to specify the test name and hashtag (#) to further specify an individual method. For example, for the following test definition:
558
559        TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)
560
561    You can run the entire test using:
562
563        atest inputflinger_tests:InputDispatcherTest
564
565    or an individual test method using:
566
567        atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents
568
569
570    - - - - - - - - - - - - - -
571    RUNNING TESTS IN ITERATION
572    - - - - - - - - - - - - - -
573
574    To run tests in iterations, simply pass --iterations argument. No matter pass or fail, atest won't stop testing until the max iteration is reached.
575
576    Example:
577        atest <test> --iterations    # 10 iterations(by default).
578        atest <test> --iterations 5  # run <test> 5 times.
579
580    Two approaches that assist users to detect flaky tests:
581
582    1) Run all tests until a failure occurs or the max iteration is reached.
583
584    Example:
585        - 10 iterations(by default).
586        atest <test> --rerun-until-failure
587        - stop when failed or reached the 20th run.
588        atest <test> --rerun-until-failure 20
589
590    2) Run failed tests until passed or the max iteration is reached.
591
592    Example:
593        - 10 iterations(by default).
594        atest <test> --retry-any-failure
595        - stop when passed or reached the 20th run.
596        atest <test> --retry-any-failure 20
597
598
599    - - - - - - - - - - - - - - - -
600    REGRESSION DETECTION (obsolute)
601    - - - - - - - - - - - - - - - -
602
603    ********************** Warning **********************
604    Please STOP using arguments below -- they are obsolete and will be removed in a near future:
605        --detect-regression
606        --generate-baseline
607        --generate-new-metrics
608
609    Please check RUNNING TESTS IN ITERATION out for alternatives.
610    ******************************************************
611
612    Generate pre-patch or post-patch metrics without running regression detection:
613
614    Example:
615        atest <test> --generate-baseline <optional iter>
616        atest <test> --generate-new-metrics <optional iter>
617
618    Local regression detection can be run in three options:
619
620    1) Provide a folder containing baseline (pre-patch) metrics (generated previously). Atest will run the tests n (default 5) iterations, generate a new set of post-patch metrics, and compare those against existing metrics.
621
622    Example:
623        atest <test> --detect-regression </path/to/baseline> --generate-new-metrics <optional iter>
624
625    2) Provide a folder containing post-patch metrics (generated previously). Atest will run the tests n (default 5) iterations, generate a new set of pre-patch metrics, and compare those against those provided. Note: the developer needs to revert the device/tests to pre-patch state to generate baseline metrics.
626
627    Example:
628        atest <test> --detect-regression </path/to/new> --generate-baseline <optional iter>
629
630    3) Provide 2 folders containing both pre-patch and post-patch metrics. Atest will run no tests but the regression detection algorithm.
631
632    Example:
633        atest --detect-regression </path/to/baseline> </path/to/new>
634
635
636    - - - - - - - - - - - -
637    TESTS IN TEST MAPPING
638    - - - - - - - - - - - -
639
640    Atest can run tests in TEST_MAPPING files:
641
642    1) Run presubmit tests in TEST_MAPPING files in current and parent
643       directories. You can also specify a target directory.
644
645    Example:
646        atest  (run presubmit tests in TEST_MAPPING files in current and parent directories)
647        atest --test-mapping </path/to/project>
648               (run presubmit tests in TEST_MAPPING files in </path/to/project> and its parent directories)
649
650    2) Run a specified test group in TEST_MAPPING files.
651
652    Example:
653        atest :postsubmit
654              (run postsubmit tests in TEST_MAPPING files in current and parent directories)
655        atest :all
656              (Run tests from all groups in TEST_MAPPING files)
657        atest --test-mapping </path/to/project>:postsubmit
658              (run postsubmit tests in TEST_MAPPING files in </path/to/project> and its parent directories)
659
660    3) Run tests in TEST_MAPPING files including sub directories
661
662    By default, atest will only search for tests in TEST_MAPPING files in current (or given directory) and its parent directories. If you want to run tests in TEST_MAPPING files in the sub-directories, you can use option --include-subdirs to force atest to include those tests too.
663
664    Example:
665        atest --include-subdirs [optional </path/to/project>:<test_group_name>]
666              (run presubmit tests in TEST_MAPPING files in current, sub and parent directories)
667    A path can be provided optionally if you want to search for tests in a given directory, with optional test group name. By default, the test group is presubmit.
668
669
670    - - - - - - - - - - - - - -
671    ADDITIONAL ARGS TO TRADEFED
672    - - - - - - - - - - - - - -
673
674    When trying to pass custom arguments for the test runners, everything after '--'
675    will be consumed as custom args.
676
677    Example:
678        atest -v <test> -- <custom_args1> <custom_args2>
679
680
681                                                     2019-12-19
682'''
683