pigweed/pw_unit_test/test.gni

# Copyright 2019 The Pigweed Authors
#
# 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
#
#     https://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.

import("//build_overrides/pigweed.gni")

import("$dir_pw_build/python_action.gni")
import("$dir_pw_build/target_types.gni")
import("$dir_pw_build/test_info.gni")
import("$dir_pw_compilation_testing/negative_compilation_test.gni")
import("$dir_pw_toolchain/generate_toolchain.gni")
import("$dir_pw_toolchain/host_clang/toolchains.gni")

declare_args() {
  # The unit test framework implementation. Defaults to
  # pw_unit_test:light, which implements a subset of GoogleTest safe to run on
  # device. Set to //pw_unit_test:googletest when using GoogleTest.
  #
  # Type: string (GN path to a source set)
  # Usage: toolchain-controlled only
  pw_unit_test_BACKEND = "$dir_pw_unit_test:light"

  # Implementation of a main function for ``pw_test`` unit test binaries. Must
  # be set to an appropriate target for the pw_unit_test backend.
  #
  # Type: string (GN path to a source set)
  # Usage: toolchain-controlled only
  pw_unit_test_MAIN = "$dir_pw_unit_test:simple_printing_main"

  # Path to a test runner to automatically run unit tests after they are built.
  #
  # If set, a ``pw_test`` target's ``<target_name>.run`` action will invoke the
  # test runner specified by this argument, passing the path to the unit test to
  # run. If this is unset, the ``pw_test`` target's ``<target_name>.run`` step
  # will do nothing.
  #
  # Targets that don't support parallelized execution of tests (e.g. a on-device
  # test runner that must flash a device and run the test in serial) should
  # set pw_unit_test_POOL_DEPTH to 1.
  #
  # Type: string (name of an executable on the PATH, or path to an executable)
  # Usage: toolchain-controlled only
  pw_unit_test_AUTOMATIC_RUNNER = ""

  # Optional list of arguments to forward to the automatic runner.
  #
  # Type: list of strings (args to pass to pw_unit_test_AUTOMATIC_RUNNER)
  # Usage: toolchain-controlled only
  pw_unit_test_AUTOMATIC_RUNNER_ARGS = []

  # Optional timeout to apply when running tests via the automatic runner.
  # Timeout is in seconds. Defaults to empty which means no timeout.
  pw_unit_test_AUTOMATIC_RUNNER_TIMEOUT = ""

  # The maximum number of unit tests that may be run concurrently for the
  # current toolchain. Setting this to 0 disables usage of a pool, allowing
  # unlimited parallelization.
  #
  # Note: A single target with two toolchain configurations (e.g. release/debug)
  #       will use two separate test runner pools by default. Set
  #       pw_unit_test_POOL_TOOLCHAIN to the same toolchain for both targets to
  #       merge the pools and force serialization.
  #
  # Type: integer
  # Usage: toolchain-controlled only
  pw_unit_test_POOL_DEPTH = 0

  # The toolchain to use when referring to the pw_unit_test runner pool. When
  # this is disabled, the current toolchain is used. This means that every
  # toolchain will use its own pool definition. If two toolchains should share
  # the same pool, this argument should be by one of the toolchains to the GN
  # path of the other toolchain.
  #
  # Type: string (GN path to a toolchain)
  # Usage: toolchain-controlled only
  pw_unit_test_POOL_TOOLCHAIN = ""

  # The name of the GN target type used to build pw_unit_test executables.
  #
  # Type: string (name of a GN template)
  # Usage: toolchain-controlled only
  pw_unit_test_EXECUTABLE_TARGET_TYPE = "pw_executable"

  # The path to the .gni file that defines pw_unit_test_EXECUTABLE_TARGET_TYPE.
  #
  # If pw_unit_test_EXECUTABLE_TARGET_TYPE is not the default of
  # `pw_executable`, this .gni file is imported to provide the template
  # definition.
  #
  # Type: string (path to a .gni file)
  # Usage: toolchain-controlled only
  pw_unit_test_EXECUTABLE_TARGET_TYPE_FILE = ""

  # If true, the pw_unit_test target, pw_test targets, and pw_test_group targets
  # will define `testonly = true`.  This is false by default for backwards
  # compatibility.
  pw_unit_test_TESTONLY = false
}

if (pw_unit_test_EXECUTABLE_TARGET_TYPE != "pw_executable" &&
    pw_unit_test_EXECUTABLE_TARGET_TYPE_FILE != "") {
  import(pw_unit_test_EXECUTABLE_TARGET_TYPE_FILE)
}

# Defines a target if enable_if is true. Otherwise, it defines that target as
# <target_name>.DISABLED and creates an empty <target_name> group. This can be
# used to conditionally create targets without having to conditionally add them
# to groups. This results in simpler BUILD.gn files.
template("pw_internal_disableable_target") {
  assert(defined(invoker.enable_if),
         "`enable_if` is required for pw_internal_disableable_target")
  assert(defined(invoker.target_type),
         "`target_type` is required for pw_internal_disableable_target")

  if (invoker.enable_if) {
    _actual_target_name = target_name
  } else {
    _actual_target_name = target_name + ".DISABLED"

    # If the target is disabled, create an empty target in its place. Use an
    # action with the original target's sources as inputs to ensure that
    # the source files exist (even if they don't compile).
    pw_python_action(target_name) {
      script = "$dir_pw_build/py/pw_build/nop.py"
      stamp = true

      inputs = []
      if (defined(invoker.sources)) {
        inputs += invoker.sources
      }
      if (defined(invoker.public)) {
        inputs += invoker.public
      }

      if (defined(invoker.source_gen_deps)) {
        deps = invoker.source_gen_deps
      }
    }
  }

  target(invoker.target_type, _actual_target_name) {
    sources = []
    public_deps = []
    deps = []
    forward_variables_from(invoker,
                           "*",
                           [
                             "enable_if",
                             "negative_compilation_tests",
                             "source_gen_deps",
                             "target_type",
                             "test_automatic_runner_args",
                           ])

    # Remove "" from dependencies. This allows disabling targets if a variable
    # (e.g. a backend) is empty.
    public_deps += [ "" ]
    public_deps -= [ "" ]
    deps += [ "" ]
    deps -= [ "" ]
    if (defined(invoker.source_gen_deps)) {
      deps += invoker.source_gen_deps
      foreach(source_gen_dep, invoker.source_gen_deps) {
        sources += get_target_outputs(source_gen_dep)
      }
    }
  }
}

# Creates a library and an executable target for a unit test with pw_unit_test.
#
# <target_name>.lib contains the provided test sources as a library, which can
# then be linked into a test executable.
# <target_name> is a standalone executable which contains only the test sources
# specified in the pw_unit_test_template.
#
# If the pw_unit_test_AUTOMATIC_RUNNER variable is set, this template also
# creates a "${test_name}.run" target which runs the unit test executable after
# building it.
#
# Targets defined using this template will produce test metadata with a
# `test_type` of "unit_test" and an additional `test_directory` value describing
# the location of the test binary within the build output.
#
# Args:
#   - enable_if: (optional) Conditionally enables or disables this test. The
#         test target and *.run target do nothing when the test is disabled. The
#         disabled test can still be built and run with the
#         <target_name>.DISABLED and <target_name>.DISABLED.run targets.
#         Defaults to true (enable_if).
#   - envvars: (optional) A list of `var_name=value` strings to set as
#         environment variables when running the target exectuable.
#   - tags: (optional) List of strings to include in the test metadata. These
#         have no effect on the build, but may be used by external tools to
#         distinguish between tests. For example, a tool may want to skip tests
#         tagged as "slow".
#   - extra_metadata: (optional) Extra metadata to include in test group
#         metadata output. This can be used to pass information about this test
#         to later build tasks.
#   - source_gen_deps: (optional) List of targets which generate `sources` for
#         this test. These `deps` will be included even if the test is disabled.
#         `get_target_outputs` is used to add the generated `sources` to the
#         test's `sources` list, so these targets must appear earlier in the
#         same build file.
#   - All of the regular "executable" target args are accepted.
#
template("pw_test") {
  # This is required in order to reference the pw_test template's target name
  # within the test_metadata of the metadata group below. The group() definition
  # creates a new scope where the "target_name" variable is set to its target,
  # shadowing the one in this scope.
  _test_target_name = target_name

  _test_is_enabled = !defined(invoker.enable_if) || invoker.enable_if

  if (pw_toolchain_COVERAGE_ENABLED) {
    _profraw_path = "$target_out_dir/test/$_test_target_name.profraw"
  }

  # Always set the output_dir as pigweed is not compatible with shared
  # bin directories for tests.
  _test_output_dir = "${target_out_dir}/test"
  if (defined(invoker.output_dir)) {
    _test_output_dir = invoker.output_dir
  }

  _test_main = pw_unit_test_MAIN
  if (defined(invoker.test_main)) {
    _test_main = invoker.test_main
  }

  # The unit test code as a source_set.
  pw_internal_disableable_target("$target_name.lib") {
    target_type = "pw_source_set"
    enable_if = _test_is_enabled
    testonly = pw_unit_test_TESTONLY

    # It is possible that the executable target type has been overriden by
    # pw_unit_test_EXECUTABLE_TARGET_TYPE, which may allow for additional
    # variables to be specified on the executable template. As such, we cannot
    # forward all variables ("*") from the invoker to source_set library, as
    # those additional variables would not be used and GN gen would error.
    _source_set_relevant_variables = [
      # GN source_set variables
      # https://gn.googlesource.com/gn/+/main/docs/reference.md#target-declarations-source_set_declare-a-source-set-target-variables
      "asmflags",
      "cflags",
      "cflags_c",
      "cflags_cc",
      "cflags_objc",
      "cflags_objcc",
      "defines",
      "include_dirs",
      "inputs",
      "ldflags",
      "lib_dirs",
      "libs",
      "precompiled_header",
      "precompiled_source",
      "rustenv",
      "rustflags",
      "swiftflags",
      "testonly",
      "assert_no_deps",
      "data_deps",
      "deps",
      "public_deps",
      "runtime_deps",
      "write_runtime_deps",
      "all_dependent_configs",
      "public_configs",
      "check_includes",
      "configs",
      "data",
      "friend",
      "metadata",
      "output_extension",
      "output_name",
      "public",
      "sources",
      "source_gen_deps",
      "visibility",

      # pw_source_set variables
      # https://pigweed.dev/pw_build/?highlight=pw_executable#target-types
      "remove_configs",
      "remove_public_deps",
    ]
    forward_variables_from(invoker, _source_set_relevant_variables)

    if (!defined(deps)) {
      deps = []
    }
    deps += [ dir_pw_unit_test ]

    if (defined(invoker.negative_compilation_tests) &&
        invoker.negative_compilation_tests) {
      deps += [
        ":$_test_target_name.nc_test",
        "$dir_pw_compilation_testing:internal_pigweed_use_only",
      ]
    }
  }

  # Metadata for this test when used as part of a pw_test_group target.
  _test_metadata = "${target_name}.metadata"
  _extra_metadata = {
    forward_variables_from(invoker, [ "extra_metadata" ])
    test_directory = rebase_path(_test_output_dir, root_build_dir)
  }
  pw_test_info(_test_metadata) {
    test_type = "unit_test"
    test_name = _test_target_name
    forward_variables_from(invoker, [ "tags" ])
    extra_metadata = _extra_metadata
  }

  pw_internal_disableable_target(_test_target_name) {
    target_type = pw_unit_test_EXECUTABLE_TARGET_TYPE
    enable_if = _test_is_enabled
    testonly = pw_unit_test_TESTONLY

    # Include configs, deps, etc. from the pw_test in the executable as well as
    # the library to ensure that linker flags propagate to the executable.
    deps = []
    forward_variables_from(invoker,
                           "*",
                           [
                             "extra_metadata",
                             "metadata",
                             "sources",
                             "source_gen_deps",
                             "public",
                           ])
    deps += [
      ":$_test_metadata",
      ":$_test_target_name.lib",
    ]
    if (_test_main != "") {
      deps += [ _test_main ]
    }
    output_dir = _test_output_dir

    metadata = {
      # N.B.: This is placed here instead of in $_test_target_name._run because
      # pw_test_group only forwards the metadata from _test_target_name and not
      # _test_target_name._run or _test_target_name.run.
      if (pw_toolchain_COVERAGE_ENABLED) {
        profraws = [
          {
            type = "profraw"
            path = rebase_path(_profraw_path, root_build_dir)
          },
        ]
      }

      # Only collect test metadata for the test itself.
      test_barrier = [ ":$_test_metadata" ]
    }
  }

  if (defined(invoker.negative_compilation_tests) &&
      invoker.negative_compilation_tests) {
    pw_cc_negative_compilation_test("$target_name.nc_test") {
      forward_variables_from(invoker, "*")
      testonly = pw_unit_test_TESTONLY

      # Add a dependency on pw_unit_test since it is implied for pw_unit_test
      # targets.
      if (!defined(deps)) {
        deps = []
      }
      deps += [ dir_pw_unit_test ]
    }
  }

  if (pw_unit_test_AUTOMATIC_RUNNER != "") {
    # When the automatic runner is set, create an action which runs the unit
    # test executable using the test runner script.
    if (_test_is_enabled) {
      _test_to_run = _test_target_name
    } else {
      # Create a run target for the .DISABLED version of the test.
      _test_to_run = _test_target_name + ".DISABLED"

      # Create a placeholder .run target for the regular version of the test.
      group(_test_target_name + ".run") {
        testonly = pw_unit_test_TESTONLY
        deps = [ ":$_test_target_name" ]
      }
    }

    _test_automatic_runner_args = pw_unit_test_AUTOMATIC_RUNNER_ARGS
    if (defined(invoker.test_automatic_runner_args)) {
      _test_automatic_runner_args = []
      _test_automatic_runner_args += invoker.test_automatic_runner_args
    }

    pw_python_action(_test_to_run + "._run") {
      # Optionally limit max test runner concurrency.
      if (pw_unit_test_POOL_DEPTH != 0) {
        _pool_toolchain = current_toolchain
        if (pw_unit_test_POOL_TOOLCHAIN != "") {
          _pool_toolchain = pw_unit_test_POOL_TOOLCHAIN
        }
        pool = "$dir_pw_unit_test:unit_test_pool($_pool_toolchain)"
      }

      deps = [ ":$_test_target_name" ]
      inputs = [ pw_unit_test_AUTOMATIC_RUNNER ]
      module = "pw_unit_test.test_runner"
      python_deps = [
        "$dir_pw_cli/py",
        "$dir_pw_unit_test/py",
      ]
      args = [
        "--runner",
        rebase_path(pw_unit_test_AUTOMATIC_RUNNER, root_build_dir),
        "--test",
        "<TARGET_FILE(:$_test_to_run)>",
      ]
      if (defined(invoker.envvars)) {
        foreach(envvars, envvars) {
          args += [
            "--env",
            envvar,
          ]
        }
      }
      if (pw_unit_test_AUTOMATIC_RUNNER_TIMEOUT != "") {
        args += [
          "--timeout",
          pw_unit_test_AUTOMATIC_RUNNER_TIMEOUT,
        ]
      }
      if (pw_toolchain_COVERAGE_ENABLED) {
        _llvm_profile_file = rebase_path(_profraw_path, root_build_dir)
        args += [
          "--env",
          "LLVM_PROFILE_FILE=" + _llvm_profile_file,
        ]
      }

      if (_test_automatic_runner_args != []) {
        args += [ "--" ] + _test_automatic_runner_args
      }

      outputs = []
      if (pw_toolchain_COVERAGE_ENABLED) {
        outputs += [ _profraw_path ]
      }
      stamp = true
    }

    group(_test_to_run + ".run") {
      testonly = pw_unit_test_TESTONLY
      public_deps = [ ":$_test_to_run._run" ]
    }
  } else {
    group(_test_target_name + ".run") {
      testonly = pw_unit_test_TESTONLY
      public_deps = [ ":$_test_target_name" ]
    }
  }
}

# Defines a related collection of unit tests.
#
# Targets defined using this template will produce test metadata with a
# `test_type` of "test_group" and an additional `deps` list describing the tests
# collected by this target.
#
# Args:
#   - tests: List of pw_test targets for each of the tests in the group.
#   - group_deps: (optional) pw_test_group targets on which this group depends.
#   - enable_if: (optional) Conditionally enables or disables this test group.
#         If false, an empty group is created. Defaults to true.
#   - output_metadata: (optional) If true, generates a JSON file containing the
#         test metadata for this group and all of its dependencies. Defaults to
#         false.
#
template("pw_test_group") {
  _group_target = target_name
  if (defined(invoker.tests)) {
    _deps = invoker.tests
  } else {
    _deps = []
  }

  # Allow empty pw_test_groups with no tests or group_deps.
  if (!defined(invoker.tests) && !defined(invoker.group_deps)) {
    not_needed("*")
  }

  _group_is_enabled = !defined(invoker.enable_if) || invoker.enable_if

  if (_group_is_enabled) {
    if (defined(invoker.group_deps)) {
      _deps += invoker.group_deps
    }

    group(_group_target + ".lib") {
      testonly = pw_unit_test_TESTONLY
      deps = []
      foreach(_target, _deps) {
        _dep_target = get_label_info(_target, "label_no_toolchain")
        _dep_toolchain = get_label_info(_target, "toolchain")
        deps += [ "$_dep_target.lib($_dep_toolchain)" ]
      }
    }

    # Create a manifest entry to indicate which tests are a part of this group.
    _test_group_metadata = "${target_name}_pw_test_group_metadata"
    _extra_metadata = {
      forward_variables_from(invoker, [ "extra_metadata" ])
      if (_deps != []) {
        deps = []
        foreach(dep, _deps) {
          deps += [ get_label_info(dep, "label_no_toolchain") ]
        }
      }
    }
    pw_test_info(_test_group_metadata) {
      testonly = pw_unit_test_TESTONLY
      build_label = _group_target
      test_type = "test_group"
      test_name = rebase_path(get_label_info(_group_target, "dir"), "//")
      extra_metadata = _extra_metadata
      deps = _deps
    }

    if (defined(invoker.output_metadata) && invoker.output_metadata) {
      generated_file(_group_target) {
        testonly = pw_unit_test_TESTONLY
        outputs = [ "$target_out_dir/$target_name.testinfo.json" ]
        data_keys = [
          "test_groups",
          "unit_tests",
          "action_tests",
          "perf_tests",
          "fuzz_tests",
        ]
        walk_keys = [ "test_barrier" ]
        output_conversion = "json"
        deps = [ ":$_test_group_metadata" ]
      }
    } else {
      group(_group_target) {
        testonly = pw_unit_test_TESTONLY
        deps = [ ":$_test_group_metadata" ]
      }
    }

    # If automatic test running is enabled, create a *.run group that collects
    # all of the individual *.run targets and groups.
    if (pw_unit_test_AUTOMATIC_RUNNER != "") {
      group(_group_target + ".run") {
        testonly = pw_unit_test_TESTONLY
        deps = [ ":$_group_target" ]
        foreach(_target, _deps) {
          _dep_target = get_label_info(_target, "label_no_toolchain")
          _dep_toolchain = get_label_info(_target, "toolchain")
          deps += [ "$_dep_target.run($_dep_toolchain)" ]
        }
      }
    }
  } else {  # _group_is_enabled
    # Create empty groups for the tests to avoid pulling in any dependencies.
    group(_group_target) {
    }
    group(_group_target + ".lib") {
    }

    if (pw_unit_test_AUTOMATIC_RUNNER != "") {
      group(_group_target + ".run") {
      }
    }

    not_needed("*")
    not_needed(invoker, "*")
  }

  # All of the tests in this group and its dependencies bundled into a single
  # test binary.
  pw_test(_group_target + ".bundle") {
    deps = [ ":$_group_target.lib" ]
    enable_if = _group_is_enabled
  }
}