kotlin_test

A kotlin_test() rule is used to define a set of .kt files that contain tests to run via JUnit.

Function Signature

def kotlin_test(
    *,
    name: str,
    default_target_platform: None | str = None,
    target_compatible_with: list[str] = [],
    compatible_with: list[str] = [],
    exec_compatible_with: list[str] = [],
    visibility: list[str] = [],
    within_view: list[str] = ["PUBLIC"],
    metadata: OpaqueMetadata = {},
    tests: list[str] = [],
    modifiers: OpaqueMetadata = [],
    _apple_platforms: dict[str, str] = {},
    _build_only_native_code: bool = select({"prelude//android/constraints:build_only_native_code": True, "DEFAULT": False}),
    _exec_os_type: str = "prelude//os_lookup/targets:os_lookup",
    _inject_test_env: str = "prelude//test/tools:inject_test_env",
    _is_building_android_binary: bool = False,
    _java_test_toolchain: str = "gh_facebook_buck2_shims_meta//:java_test",
    _java_toolchain: str = "gh_facebook_buck2_shims_meta//:java",
    _kotlin_toolchain: str = "gh_facebook_buck2_shims_meta//:kotlin",
    _remote_test_execution_toolchain: str = "gh_facebook_buck2_shims_meta//:remote_test_execution",
    _test_toolchain: str = "gh_facebook_buck2_shims_meta//:test",
    abi_generation_mode: None | str = None,
    annotation_processing_tool: None | str = None,
    annotation_processor_deps: list[str] = [],
    annotation_processor_params: list[str] = [],
    annotation_processors: list[str] = [],
    contacts: list[str] = [],
    cxx_library_allowlist: list[str] = [],
    default_cxx_platform: None | str = None,
    default_host_platform: None | str = None,
    deps: list[str] = [],
    deps_query: None | str = None,
    enable_used_classes: bool = True,
    env: dict[str, str] = {},
    exported_deps: list[str] = [],
    exported_provided_deps: list[str] = [],
    extra_arguments: list[str] = [],
    extra_kotlinc_arguments: list[str] = [],
    fork_mode: str = "none",
    friend_paths: list[str] = [],
    incremental: bool = False,
    java: None | str = None,
    java_agents: list[str] = [],
    java_version: None | str = None,
    javac: None | str = None,
    k2: bool = False,
    kotlin_compiler_plugins: list[(str, dict[str, str])] = [],
    labels: list[str] = [],
    licenses: list[str] = [],
    manifest_file: None | str = None,
    maven_coords: None | str = None,
    never_mark_as_unused_dependency: None | bool = None,
    no_x_jdk_release: bool = False,
    non_exec_dep_plugins_deprecated: list[str | (str, list[str])] = [],
    on_unused_dependencies: None | str = None,
    plugins: list[str | (str, list[str])] = [],
    proguard_config: None | str = None,
    provided_deps: list[str] = [],
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str | list[str]]] = None,
    remove_classes: list[str] = [],
    required_for_source_only_abi: bool = False,
    resources: list[str] = [],
    resources_root: None | str = None,
    run_test_separately: bool = False,
    runtime_deps: list[str] = [],
    source: None | str = None,
    source_abi_verification_mode: None | str = None,
    source_only_abi_deps: list[str] = [],
    srcs: list[str] = [],
    std_err_log_level: None | int | str = None,
    std_out_log_level: None | int | str = None,
    target: None | str = None,
    test_case_timeout_ms: None | int = None,
    test_class_names_file: None | str = None,
    test_rule_timeout_ms: None | int = None,
    test_type: None | str = None,
    unbundled_resources_root: None | str = None,
    use_cxx_libraries: None | bool = None,
    use_dependency_order_classpath: None | bool = None,
    use_jvm_abi_gen: None | bool = None,
    vm_args: list[str] = [],
) -> None

Parameters

name: (required)

name of the target
default_target_platform: (defaults to: None)

specifies the default target platform, used when no platforms are specified on the command line
target_compatible_with: (defaults to: [])

a list of constraints that are required to be satisfied for this target to be compatible with a configuration
compatible_with: (defaults to: [])

a list of constraints that are required to be satisfied for this target to be compatible with a configuration
exec_compatible_with: (defaults to: [])

a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
visibility: (defaults to: [])

a list of visibility patterns restricting what targets can depend on this one
within_view: (defaults to: ["PUBLIC"])

a list of visibility patterns restricting what this target can depend on
metadata: (defaults to: {})

a key-value map of metadata associated with this target
tests: (defaults to: [])

a list of targets that provide tests for this one
modifiers: (defaults to: [])

an array of modifiers associated with this target
cxx_library_allowlist: (defaults to: [])

List of cxx_library targets to build, if use_cxx_libraries is true. This can be useful if some dependencies are Android-only and won't build for the test host platform.
deps: (defaults to: [])

Same as kotlin_library(). // org.junit.rules.Timeout was not introduced until 4.7. Must include JUnit (version 4.7 or later) as a dependency for JUnit tests. Must include TestNG (version 6.2 or later) and hamcrest as a dependencies for TestNG tests.
enable_used_classes: (defaults to: True)

Deprecated: for an experiment only, will be removed
env: (defaults to: {})

A map of environment names and values to set when running the test.
fork_mode: (defaults to: "none")

Controls whether tests will all be run in the same process or a process will be started for each set of tests in a class.

(This is mainly useful when porting Java tests to Buck from Apache Ant which allows JUnit tasks to set a fork="yes" property. It should not be used for new tests since it encourages tests to not cleanup after themselves and increases the tests' computational resources and running time.)

none All tests will run in the same process. per_test A process will be started for each test class in which all tests of that test class will run.
incremental: (defaults to: False)

Enables Kotlin incremental compilation.
javac: (defaults to: None)

Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.
k2: (defaults to: False)

Enables the Kotlin K2 compiler.

kotlin_compiler_plugins: (defaults to: [])

Use this to specify Kotlin compiler plugins to use when compiling this library. This takes a map, with each entry specify one plugin. Entry's key is plugin source path, and value is a map of plugin option key value pair. Unlike extra_kotlinc_arguments, these can be source paths, not just strings.

A special option value is __codegen_dir__, in which case Buck will provide a default codegen folder's path as option value instead. E.g.

fbcode/buck2/prelude/decls/jvm_common.bzl
kotlin_compiler_plugins = {
    "somePluginSourcePath": {
        "plugin:somePluginId:somePluginOptionKey": "somePluginOptionValue",
        "plugin:somePluginId:someDirectoryRelatedOptionKey": "__codegen_dir__",
    },
},

Each plugin source path will be prefixed with -Xplugin= and passed as extra arguments to the compiler. Plugin options will be appended after its plugin with -P.

A specific example is, if you want to use kotlinx.serialization with kotlin_library(), you need to specify kotlinx-serialization-compiler-plugin.jar under kotlin_compiler_plugins and kotlinx-serialization-runtime.jar (which you may have to fetch from Maven) in your deps:

kotlin_library(
    name = "example",
    srcs = glob(["*.kt"]),
    deps = [
        ":kotlinx-serialization-runtime",
    ],
    kotlin_compiler_plugins = {
        # Likely copied from your $KOTLIN_HOME directory.
        "kotlinx-serialization-compiler-plugin.jar": {},
    },
)

prebuilt_jar(
    name = "kotlinx-serialization-runtime",
    binary_jar = ":kotlinx-serialization-runtime-0.10.0",
)

# Note you probably want to set
# maven_repo=http://jcenter.bintray.com/ in your .buckconfig until
# https://github.com/Kotlin/kotlinx.serialization/issues/64
# is closed.
remote_file(
    name = "kotlinx-serialization-runtime-0.10.0",
    out = "kotlinx-serialization-runtime-0.10.0.jar",
    url = "mvn:org.jetbrains.kotlinx:kotlinx-serialization-runtime:jar:0.10.0",
    sha1 = "23d777a5282c1957c7ce35946374fff0adab114c"
)

labels: (defaults to: [])

A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g., smoke or fast). A label can be used to filter or include a specific test rule when executing buck test
no_x_jdk_release: (defaults to: False)

By default, classic kotlin adds -Xjdk-release=java_version to the kotlinc arguments. Set this to True to not add -Xjdk-release=java_version to the kotlinc arguments. This is helpful if the -Xjdk-release= brings trouble since it is not 100% guaranteed to work as expected. See the doc of kotlinc for more detail.
non_exec_dep_plugins_deprecated: (defaults to: [])

Plugins that do not use the execution platform. This exists for historical reasons, and should not be used. Use plugins instead - plugins should be configured for the execution platform since that is where they are used.
plugins: (defaults to: [])

List of plugins that should be run during compilation of the target. A list of strings may additionally be provided in order to pass additional arguments to the plugin.
resources: (defaults to: [])

Same as kotlin_library().
srcs: (defaults to: [])

Like kotlin_library(), all of the .kt files specified by the srcs argument will be compiled when this rule is built. In addition, all of the corresponding .class files that are built by this rule will be passed as arguments to JUnit when this rule is run as a test. .class files that are passed to JUnit that do not have any methods annotated with @Test are considered failed tests, so make sure that only test case classes are specified as srcs. This is frequently done by specifying srcs as glob(['**/*Test.kt']).
std_err_log_level: (defaults to: None)

Same as std_out_log_level, but for std err.
std_out_log_level: (defaults to: None)

Log level for messages from the source under test that buck will output to std out. Value must be a valid java.util.logging.Level value.
test_rule_timeout_ms: (defaults to: None)

If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the default rule_timeout if any has been specified in .buckconfig .
test_type: (defaults to: None)

Specifies which test framework to use. The currently supported options are 'junit' and 'testng'.
vm_args: (defaults to: [])

Runtime arguments to the JVM running the tests.

Function Signature​

Parameters​

Function Signature

Parameters