erlang_test
name
def name(
*,
name: str,
default_target_platform: None | str = ...,
target_compatible_with: list[str] = ...,
compatible_with: list[str] = ...,
exec_compatible_with: list[str] = ...,
visibility: list[str] = ...,
within_view: list[str] = ...,
metadata: OpaqueMetadata = ...,
tests: list[str] = ...,
modifiers: OpaqueMetadata = ...,
_apple_platforms: dict[str, str] = ...,
_artifact_annotation_mfa: str = ...,
_cli_lib: str = ...,
_ct_opts: str = ...,
_providers: str = ...,
_test_binary_lib: str = ...,
_toolchain: str = ...,
_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] = ...,
preamble: str = ...,
property_tests: list[str] = ...,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str | list[str]]] = ...,
resources: list[str] = ...,
shell_configs: list[str] = ...,
shell_libs: list[str] = ...,
suite: str,
) -> None
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
.
Parameters
-
name
: name of the target -
default_target_platform
: specifies the default target platform, used when no platforms are specified on the command line -
target_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configuration -
compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configuration -
exec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform -
visibility
: a list of visibility patterns restricting what targets can depend on this one -
within_view
: a list of visibility patterns restricting what this target can depend on -
metadata
: a key-value map of metadata associated with this target -
tests
: a list of targets that provide tests for this one -
modifiers
: an array of modifiers associated with this target -
common_app_env
: Application environment variables for thecommon
application. -
config_files
: 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 thenexport_file
rule, as in the example below. -
deps
: The set of dependencies needed for all suites included in the target to compile and run. They could be eithererlang_app(lication)
orerlang_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 thesrcs
field of theerlang_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
: Add the given values to the environment variables with which the test is executed. -
extra_ct_hooks
: List of additional Common Test hooks. The strings are interpreted as Erlang terms. -
extra_erl_flags
: List of additional command line arguments given to the erl command invocation. These arguments are added to the front of the argument list. -
os_env
: This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain. -
resources
: Theresources
field specifies targets whose default output are placed in the testdata_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 anerlang_escript
target. -
shell_configs
: This attribute allows to set config files for the shell. The dependencies that are typically used here areexport_file
targets. -
shell_libs
: This attribute allows to define additional dependencies for the shell. By default this is set to["prelude//erlang/shell:buck2_shell_utils"]
which includes auser_default
module that loads and compiles modules with buck2 mechanisms. -
suite
: The source file for the test suite. If you are using the macro, you should use thesuites
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.
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 patterngroup.mycase
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"], )