tools/android_test_mapping_format.py

#!/usr/bin/env python3
# Copyright 2018 The Android Open Source Project
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Validates TEST_MAPPING files in Android source code.

The goal of this script is to validate the format of TEST_MAPPING files:
1. It must be a valid json file.
2. Each test group must have a list of test that containing name and options.
3. Each import must have only one key `path` and one value for the path to
   import TEST_MAPPING files.
"""

import argparse
import json
import os
import re
import sys
from typing import Any, Dict

_path = os.path.realpath(__file__ + "/../..")
if sys.path[0] != _path:
    sys.path.insert(0, _path)
del _path

# We have to import our local modules after the sys.path tweak.  We can't use
# relative imports because this is an executable program, not a module.
# pylint: disable=wrong-import-position
import rh.git

_IMPORTS = "imports"
_NAME = "name"
_OPTIONS = "options"
_PATH = "path"
_HOST = "host"
_PREFERRED_TARGETS = "preferred_targets"
_FILE_PATTERNS = "file_patterns"
_INVALID_IMPORT_CONFIG = "Invalid import config in TEST_MAPPING file"
_INVALID_TEST_CONFIG = "Invalid test config in TEST_MAPPING file"
_TEST_MAPPING_URL = (
    "https://source.android.com/compatibility/tests/development/test-mapping"
)

# Pattern used to identify line-level '//'-format comment in TEST_MAPPING file.
_COMMENTS_RE = re.compile(r"^\s*//")


class Error(Exception):
    """Base exception for all custom exceptions in this module."""


class InvalidTestMappingError(Error):
    """Exception to raise when detecting an invalid TEST_MAPPING file."""


def _filter_comments(json_data: str) -> str:
    """Removes '//'-format comments in TEST_MAPPING file to valid format.

    Args:
        json_data: TEST_MAPPING file content (as a string).

    Returns:
        Valid json string without comments.
    """
    return "".join(
        "\n" if _COMMENTS_RE.match(x) else x for x in json_data.splitlines()
    )


def _validate_import(entry: Dict[str, Any], test_mapping_file: str):
    """Validates an import setting.

    Args:
        entry: A dictionary of an import setting.
        test_mapping_file: Path to the TEST_MAPPING file to be validated.

    Raises:
        InvalidTestMappingError: if the import setting is invalid.
    """
    if len(entry) != 1:
        raise InvalidTestMappingError(
            f"{_INVALID_IMPORT_CONFIG} {test_mapping_file}. Each import can "
            f"only have one `path` setting. Failed entry: {entry}"
        )
    if _PATH not in entry:
        raise InvalidTestMappingError(
            f"{_INVALID_IMPORT_CONFIG} {test_mapping_file}. Import can "
            f"only have one `path` setting. Failed entry: {entry}"
        )


def _validate_test(test: Dict[str, Any], test_mapping_file: str) -> bool:
    """Returns whether a test declaration is valid.

    Args:
        test: A dictionary of a test declaration.
        test_mapping_file: Path to the TEST_MAPPING file to be validated.

    Raises:
        InvalidTestMappingError: if the a test declaration is invalid.
    """
    if _NAME not in test:
        raise InvalidTestMappingError(
            f"{_INVALID_TEST_CONFIG} {test_mapping_file}. Test config must "
            f"have a `name` setting. Failed test config: {test}"
        )

    if not isinstance(test.get(_HOST, False), bool):
        raise InvalidTestMappingError(
            f"{_INVALID_TEST_CONFIG} {test_mapping_file}. `host` setting in "
            f"test config can only have boolean value of `true` or `false`. "
            f"Failed test config: {test}"
        )

    for key in (_PREFERRED_TARGETS, _FILE_PATTERNS):
        value = test.get(key, [])
        if not isinstance(value, list) or any(
            not isinstance(t, str) for t in value
        ):
            raise InvalidTestMappingError(
                f"{_INVALID_TEST_CONFIG} {test_mapping_file}. `{key}` setting "
                f"in test config can only be a list of strings. "
                f"Failed test config: {test}"
            )

    for option in test.get(_OPTIONS, []):
        if not isinstance(option, dict):
            raise InvalidTestMappingError(
                f"{_INVALID_TEST_CONFIG} {test_mapping_file}. Option setting "
                f"in test config can only be a dictionary of key-val setting. "
                f"Failed entry: {option}"
            )
        if len(option) != 1:
            raise InvalidTestMappingError(
                f"{_INVALID_TEST_CONFIG} {test_mapping_file}. Each option "
                f"setting can only have one key-val setting. "
                f"Failed entry: {option}"
            )


def process_file(test_mapping_file: str):
    """Validates a TEST_MAPPING file content."""
    try:
        test_mapping_data = json.loads(_filter_comments(test_mapping_file))
    except ValueError as exception:
        # The file is not a valid JSON file.
        print(
            f"Invalid JSON data in TEST_MAPPING file "
            f"Failed to parse JSON data: {test_mapping_file}, "
            f"error: {exception}",
            file=sys.stderr,
        )
        raise

    for group, value in test_mapping_data.items():
        if group == _IMPORTS:
            # Validate imports.
            for test in value:
                _validate_import(test, test_mapping_file)
        else:
            # Validate tests.
            for test in value:
                _validate_test(test, test_mapping_file)


def get_parser():
    """Returns a command line parser."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--commit", type=str, help="Specify the commit to validate."
    )
    parser.add_argument("project_dir")
    parser.add_argument("files", nargs="+")
    return parser


def main(argv):
    """Main function."""
    parser = get_parser()
    opts = parser.parse_args(argv)
    try:
        for filename in opts.files:
            if opts.commit:
                json_data = rh.git.get_file_content(opts.commit, filename)
            else:
                with open(
                    os.path.join(opts.project_dir, filename), encoding="utf-8"
                ) as file:
                    json_data = file.read()
            process_file(json_data)
    except:
        print(
            f"Visit {_TEST_MAPPING_URL} for details about the format of "
            "TEST_MAPPING file.",
            file=sys.stderr,
        )
        raise


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))