# Copyright 2020 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

import("fuchsia_component.gni")

# Defines a component that launches a test.
# See: https://fuchsia.dev/fuchsia-src/development/components/build
#
# This template is a useful shortcut for defining classic unit tests for target
# devices, but (unlike fuchsia_unittest_package) where you have multiple test
# targets and want to bundle them in a single test package.
# Pure unit tests don't require any special capabilities, so their component
# manifest can be generated by the template if a manifest is not specified.
#
# Example:
# ```
# executable("rot13_encoder_test") {
#   sources = [ "rot13_encoder_test.cc" ]
#   testonly = true
# }
#
# fuchsia_unittest_component("rot13-encoder-test") {
#   executable_path = "bin/rot13_encoder_decoder_test"
#   deps = [ ":rot13_encoder_decoder_test" ]
# }
#
# executable("rot13_decoder_test") {
#   sources = [ "rot13_decoder_test.cc" ]
#   testonly = true
# }
#
# fuchsia_unittest_component("rot13-decoder-test") {
#   executable_path = "bin/rot13_decoder_test"
#   deps = [ ":rot13_decoder_test" ]
# }
#
# fuchsia_test_package("rot13-tests") {
#   test_components = [
#     ":rot13-encoder-test",
#     ":rot13-decoder-test",
#   ]
# }
# ```
#
# The above will generate a manifest for each test and include both components in a single package,
# which can be run with the launch URLs:
# fuchsia-pkg://fuchsia.com/rot13-tests#meta/rot13-encoder-test.cmx
# fuchsia-pkg://fuchsia.com/rot13-tests#meta/rot13-decoder-test.cmx
#
# Parameters
#
#   manifest (required if `executable_path` is not specified)
#     Specify a component manifest for the test.
#     If a manifest is not specified, a trivial manifest will be generated.
#     The generated manifest requests no special capabilities, which is good
#     enough for "pure" unit tests.
#     To view the generated manifest, see:
#     `fx gn outputs out/default path/to/your:<target_name>_generated_manifest`
#     Type: path
#
#   executable_path (required if `manifest` is not specified)
#     Specify the packaged path of the test executable.
#     Example: "test/my_executable"
#     This executable must be generated by one of the `deps`.
#     This is used in generating the manifest.
#     Type: string
#
#   executable_args (ignored if `manifest` is specified)
#     Specify the args to be passed to test executable.
#     Example: ["--foo", "bar"]
#     This is used in generating the manifest.
#     Type: list of string
#
#   component_name (optional)
#     The name of the component.
#     Type: string
#     Default: target_name
#
#   v2_test_runner (optional)
#     If specified and no manifest is specified, a trivial Components v2
#     manifest will be generated using the specified test runner. The
#     generated manifest will include temporary storage at /tmp but no other
#     special capabilities. Typical values: "rust_test_runner",
#     "gtest_runner" or "go_test_runner".
#     Type: string
#
#   deps
#   visibility
template("fuchsia_unittest_component") {
  if (defined(invoker.manifest)) {
    assert(
        !defined(invoker.executable_path),
        "Either `manifest` or `executable_path` must be specified when calling fuchsia_unittest_component($target_name)")
    assert(
        !defined(invoker.executable_args),
        "Specifying `executable_args` has no effect when specifying `manifest` when calling fuchsia_unittest_component($target_name)")
  } else {
    generated_target = "${target_name}_generated_manifest"
    generated_file(generated_target) {
      program_stanza = {
        binary = invoker.executable_path
        if (defined(invoker.executable_args)) {
          args = invoker.executable_args
        }
      }
      if (defined(invoker.v2_test_runner)) {
        contents = {
          include = [ "sdk/lib/diagnostics/syslog/client.shard.cml" ]
          program = program_stanza
          capabilities = [
            {
              protocol = "fuchsia.test.Suite"
            },
          ]
          use = [
            {
              runner = invoker.v2_test_runner
            },
            {
              storage = "temp"
              path = "/tmp"
            },
          ]
          expose = [
            {
              protocol = "fuchsia.test.Suite"
              from = "self"
            },
          ]
        }
        outputs = [ "$target_out_dir/${generated_target}.cml" ]
      } else {
        contents = {
          include = [ "sdk/lib/diagnostics/syslog/client.shard.cmx" ]
          program = program_stanza
        }
        outputs = [ "$target_out_dir/${generated_target}.cmx" ]
      }
      output_conversion = "json"
      testonly = true
      visibility = [ ":*" ]
    }

    manifest = get_target_outputs(":$generated_target")
    manifest = manifest[0]
  }

  fuchsia_component(target_name) {
    forward_variables_from(invoker,
                           [
                             "deps",
                             "manifest",
                             "visibility",
                           ])
    component_name = target_name
    if (defined(invoker.component_name)) {
      component_name = invoker.component_name
    }
    testonly = true

    if (defined(generated_target)) {
      if (!defined(deps)) {
        deps = []
      }
      deps += [ ":$generated_target" ]
    }
  }
}