erlang_test

The erlang_test ruls defines a test target for a single test suite. In most cases you want to define multiple suites in one go. The erlang_tests macro allows users to generate erlang_test targets for multiple test suites. Each suite <name>_SUITE.erl will have a generated hidden erlang_test target whose name is <name>_SUITE.

Details

Each erlang_test target implements tests using the Common Test library OTP documentation. They can, although it is not recommended, also act as dependencies of other tests. The default output of this rule is a "test_folder", consisting of the compiled test suite and the data directory.

For each suite <name>_SUITE.erl, if a data_dir <name>_SUITE_data is present along the suite, (as per the data_dir naming scheme for ct), it will automatically adds the corresponding resource target to the generated test target of the suite. Resources will be placed in the Data directory (data_dir) of each of the suite.

It allows the writer of the rule to add global configuration files and global default dependencies (e.g meck). These ones should be specified using global variables erlang.erlang_tests_default_apps and erlang.erlang_tests_default_config respectively.

The erlang_tests macro forwards all attributes to the erlang_test. It defines some attributes that control how the targets get generated:

• srcs ([source]): Set of files that the suites might depend on and that are not part of any specific application. A "meta" application having those files as sources will automatically be created, and included in the dependencies of the tests.

One can call

• buck2 build //my_app:test_SUITE to compile the test files together with its dependencies.
• buck2 test //my_app:other_test_SUITE to run the test.
• buck2 run //my_app:other_test_SUITE to open an interactive test shell, where tests can be run iteratively.

buck2 test will rely on tpx to run the suite. To get access to tpx commands, add -- after the target. For example:

• buck2 test //my_app:other_test_SUITE -- --help will print the list of tpx available command line parameters.
• buck2 test //my_app:other_test_SUITE -- group.mycase will only run those test cases that match the pattern group.mycase

Function Signature

def erlang_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] = {},
    _artifact_annotation_mfa: str = "artifact_annotations:default_annotation/1",
    _cli_lib: str = "prelude//erlang/common_test/test_cli_lib:test_cli_lib",
    _ct_opts: str = "",
    _inner_trampolines: list[str] = [],
    _providers: str = "",
    _test_binary_lib: str = "prelude//erlang/common_test/test_binary:test_binary",
    _toolchain: str = "gh_facebook_buck2_shims_meta//:erlang-default",
    _trampolines: list[str] = [],
    common_app_env: dict[str, str] = {},
    config_files: list[str] = [],
    contacts: list[str] = [],
    deps: list[str] = [],
    env: dict[str, str] = {},
    extra_ct_hooks: list[str] = [],
    extra_erl_flags: list[str] = [],
    labels: list[str] = [],
    os_env: None | dict[str, str] = None,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str | list[str]]] = None,
    resources: list[str] = [],
    shell_configs: list[str] = [],
    shell_libs: list[str] = ["prelude//erlang/shell:buck2_shell_utils"],
    suite: 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

• _inner_trampolines: (defaults to: [])

  trampolines that are used for the test node

• _trampolines: (defaults to: [])

  trampolines that are used for the test binary

• common_app_env: (defaults to: {})

  Application environment variables for the common application.

• config_files: (defaults to: [])

  Will specify what config files the erlang beam machine running test with should load, for reference look at OTP documentation. These ones should consist of default_output of some targets. In general, this field is filled with target coming from then export_file rule, as in the example below.

• contacts: (defaults to: [])

  A list of organizational contacts for this rule. These could be individuals who you would contact in the event of a failure or other issue with the rule.

  contacts = [ 'Joe Sixpack', 'Erika Mustermann' ]

• deps: (defaults to: [])

  The set of dependencies needed for all suites included in the target to compile and run. They could be either erlang_app(lication) or erlang_test targets, although the latter is discouraged. If some suites need to access common methods, a common helper file should be created and included in the srcs field of the erlang_tests target. If some applications are included as dependencies of this target, their private include will automatically be pulled and made available for the test. That allows tests to access the private header files from the applications under test.

• env: (defaults to: {})

  Add the given values to the environment variables with which the test is executed.

• extra_ct_hooks: (defaults to: [])

  List of additional Common Test hooks. The strings are interpreted as Erlang terms.

• extra_erl_flags: (defaults to: [])

  List of additional command line arguments given to the erl command invocation. These arguments are added to the front of the argument list.

• labels: (defaults to: [])

  Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query().

• os_env: (defaults to: None)

  This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain.

• resources: (defaults to: [])

  The resources field specifies targets whose default output are placed in the test data_dir directory for all the suites present in the macro target. Additionally, if data directory are present in the directory along the suite, this one will be pulled automatically for the relevant suite.

  Any target can be used, e.g. if you want to place a built escript in the data_dir directory, you can use an erlang_escript target.

• shell_configs: (defaults to: [])

  This attribute allows to set config files for the shell. The dependencies that are typically used here are export_file targets.

• shell_libs: (defaults to: ["prelude//erlang/shell:buck2_shell_utils"])

  This attribute allows to define additional dependencies for the shell. By default this is set to ["prelude//erlang/shell:buck2_shell_utils"] which includes a user_default module that loads and compiles modules with buck2 mechanisms.

• suite: (required)

  The source file for the test suite. If you are using the macro, you should use the suites attribute instead.

  The suites attribute specifies which erlang_test targets should be generated. For each suite "path_to_suite/suite_SUITE.erl" an implicit 'erlang_test' target suite_SUITE will be generated.

Examples

erlang_test( name = "unit_test_SUITE", suite = "unit_test_SUTIE.erl", deps = [":my_other_app"], contacts = ["author@email.com"], )

erlang_tests( suites = ["test_SUITE.erl", "other_test_SUITE".erl], deps = [":my_app"], contacts = ["author@email.com"], )