Existen varios enfoques diferentes para probar el código de Starlark en Bazel. En esta página, se recopilan las prácticas recomendadas y los frameworks actuales por caso de uso.
Prueba reglas
Skylib tiene un framework de prueba llamado unittest.bzl para verificar el comportamiento de tiempo de análisis de las reglas, como sus acciones y proveedores. Estas pruebas se denominan "pruebas de análisis" y, actualmente, son la mejor opción para probar el funcionamiento interno de las reglas.
Algunas advertencias:
Las aserciones de prueba ocurren dentro de la compilación, no en un proceso del ejecutor de pruebas independiente. Los destinos que crea la prueba deben nombrarse de manera que no colisionen con los destinos de otras pruebas o de la compilación. Bazel considera un error que ocurre durante la prueba como una falla de compilación en lugar de una falla de prueba.
Se requiere una buena cantidad de código estándar para configurar las reglas que se prueban y las que contienen las aserciones de prueba. Esta plantilla puede parecer abrumador al principio. Resulta útil tener en cuenta que las macros se evalúan y los objetivos se generan durante la fase de carga, mientras que las funciones de implementación de reglas no se ejecutan hasta más tarde, durante la fase de análisis.
Las pruebas de análisis están diseñadas para ser bastante pequeñas y livianas. Algunas funciones del framework de pruebas de análisis están restringidas a la verificación de destinos con una cantidad máxima de dependencias transitivas (actualmente, 500). Esto se debe a las implicaciones de rendimiento del uso de estas funciones con pruebas más grandes.
El principio básico es definir una regla de prueba que dependa de la regla que está a prueba. Esto le otorga a la regla de prueba acceso a los proveedores de la regla que está a prueba.
La función de implementación de la regla de prueba realiza aserciones. Si hay
alguna falla, esta no se genera de inmediato si se llama a fail() (que activaría
un error de compilación en el momento del análisis), sino mediante el almacenamiento de los errores en una
secuencia de comandos generada que falla en el momento de la ejecución de la prueba.
A continuación, se muestra un ejemplo mínimo de juguete, seguido de otro que comprueba las acciones.
Ejemplo mínimo
//mypkg/myrules.bzl:
MyInfo = provider(fields = {
"val": "string value",
"out": "output File",
})
def _myrule_impl(ctx):
"""Rule that just generates a file and returns a provider."""
out = ctx.actions.declare_file(ctx.label.name + ".out")
ctx.actions.write(out, "abc")
return [MyInfo(val="some value", out=out)]
myrule = rule(
implementation = _myrule_impl,
)
//mypkg/myrules_test.bzl:
load("@bazel_skylib//lib:unittest.bzl", "asserts", "analysistest")
load(":myrules.bzl", "myrule", "MyInfo")
# ==== Check the provider contents ====
def _provider_contents_test_impl(ctx):
env = analysistest.begin(ctx)
target_under_test = analysistest.target_under_test(env)
# If preferred, could pass these values as "expected" and "actual" keyword
# arguments.
asserts.equals(env, "some value", target_under_test[MyInfo].val)
# If you forget to return end(), you will get an error about an analysis
# test needing to return an instance of AnalysisTestResultInfo.
return analysistest.end(env)
# Create the testing rule to wrap the test logic. This must be bound to a global
# variable, not called in a macro's body, since macros get evaluated at loading
# time but the rule gets evaluated later, at analysis time. Since this is a test
# rule, its name must end with "_test".
provider_contents_test = analysistest.make(_provider_contents_test_impl)
# Macro to setup the test.
def _test_provider_contents():
# Rule under test. Be sure to tag 'manual', as this target should not be
# built using `:all` except as a dependency of the test.
myrule(name = "provider_contents_subject", tags = ["manual"])
# Testing rule.
provider_contents_test(name = "provider_contents_test",
target_under_test = ":provider_contents_subject")
# Note the target_under_test attribute is how the test rule depends on
# the real rule target.
# Entry point from the BUILD file; macro for running each test case's macro and
# declaring a test suite that wraps them together.
def myrules_test_suite(name):
# Call all test functions and wrap their targets in a suite.
_test_provider_contents()
# ...
native.test_suite(
name = name,
tests = [
":provider_contents_test",
# ...
],
)
//mypkg/BUILD:
load(":myrules.bzl", "myrule")
load(":myrules_test.bzl", "myrules_test_suite")
# Production use of the rule.
myrule(
name = "mytarget",
)
# Call a macro that defines targets that perform the tests at analysis time,
# and that can be executed with "bazel test" to return the result.
myrules_test_suite(name = "myrules_test")
La prueba se puede ejecutar con bazel test //mypkg:myrules_test.
Además de las sentencias load() iniciales, el archivo consta de dos partes principales:
Las pruebas en sí, cada una de las cuales consta de 1) una función de implementación de tiempo de análisis para la regla de prueba, 2) una declaración de la regla de prueba a través de
analysistest.make()y 3) una función de tiempo de carga (macro) para declarar la regla en prueba (y sus dependencias) y la regla de prueba. Si las aserciones no cambian entre casos de prueba, los puntos 1) y 2) se pueden compartir en varios casos de prueba.La función del paquete de pruebas, que llama a las funciones de tiempo de carga para cada prueba y declara un objetivo
test_suiteque agrupa todas las pruebas
Para mantener la coherencia, sigue la convención de nombres recomendada: foo representa la parte del nombre de la prueba que describe lo que la prueba verifica (provider_contents en el ejemplo anterior). Por ejemplo, un método de prueba de JUnit se llamaría testFoo.
Luego, haz lo siguiente:
la macro que genera la prueba y el destino a prueba debe llamarse
_test_foo(_test_provider_contents).el tipo de regla de prueba debe llamarse
foo_test(provider_contents_test).la etiqueta del destino de este tipo de regla debe ser
foo_test(provider_contents_test)la función de implementación para la regla de prueba debe llamarse
_foo_test_impl(_provider_contents_test_impl).las etiquetas de los destinos de las reglas que se están probando y sus dependencias deben tener el prefijo
foo_(provider_contents_)
Ten en cuenta que las etiquetas de todos los destinos pueden entrar en conflicto con otras del mismo paquete de COMPILACIÓN, por lo que resulta útil usar un nombre único para la prueba.
Pruebas de fallas
Puede ser útil verificar que una regla falla en función de determinadas entradas o en cierto estado. Esto se puede hacer con el marco de trabajo de prueba de análisis:
La regla de prueba creada con analysistest.make debe especificar expect_failure:
failure_testing_test = analysistest.make(
_failure_testing_test_impl,
expect_failure = True,
)
La implementación de la regla de prueba debe realizar aserciones sobre la naturaleza de la falla que se produjo (específicamente, el mensaje de falla):
def _failure_testing_test_impl(ctx):
env = analysistest.begin(ctx)
asserts.expect_failure(env, "This rule should never work")
return analysistest.end(env)
Además, asegúrate de que el destino que estás probando esté etiquetado específicamente como "manual".
Sin esto, compilar todos los destinos en tu paquete con :all dará como resultado una compilación del destino que falla intencionalmente y se exhibirá una falla de compilación. Con
“manual”, el destino que estás probando se compilará solo si se especifica de forma explícita o como
una dependencia de un destino no manual (como tu regla de prueba):
def _test_failure():
myrule(name = "this_should_fail", tags = ["manual"])
failure_testing_test(name = "failure_testing_test",
target_under_test = ":this_should_fail")
# Then call _test_failure() in the macro which generates the test suite and add
# ":failure_testing_test" to the suite's test targets.
Verifica las acciones registradas
Es posible que desees escribir pruebas que realicen aserciones sobre las acciones que registra tu
regla, por ejemplo, mediante ctx.actions.run(). Esto se puede hacer en tu función de implementación de reglas de prueba de análisis. Un ejemplo:
def _inspect_actions_test_impl(ctx):
env = analysistest.begin(ctx)
target_under_test = analysistest.target_under_test(env)
actions = analysistest.target_actions(env)
asserts.equals(env, 1, len(actions))
action_output = actions[0].outputs.to_list()[0]
asserts.equals(
env, target_under_test.label.name + ".out", action_output.basename)
return analysistest.end(env)
Ten en cuenta que analysistest.target_actions(env) muestra una lista de objetos Action que representan acciones registradas por el destino que se está probando.
Verifica el comportamiento de la regla con diferentes marcas
Te recomendamos que verifiques el comportamiento de tu regla real de una manera determinada en función de ciertas marcas de compilación. Por ejemplo, tu regla puede comportarse de manera diferente si un usuario especifica lo siguiente:
bazel build //mypkg:real_target -c opt
versus
bazel build //mypkg:real_target -c dbg
A primera vista, esto se puede hacer probando el destino que se está probando con las marcas de compilación deseadas:
bazel test //mypkg:myrules_test -c opt
Sin embargo, se vuelve imposible que tu paquete de pruebas contenga simultáneamente una prueba que verifica el comportamiento de la regla en -c opt y otra prueba que verifica el comportamiento de la regla en -c dbg. No se podrán ejecutar ambas pruebas
en la misma compilación.
Para solucionar este problema, especifica las marcas de compilación deseadas cuando definas la regla de prueba:
myrule_c_opt_test = analysistest.make(
_myrule_c_opt_test_impl,
config_settings = {
"//command_line_option:compilation_mode": "opt",
},
)
Por lo general, el destino que se está probando se analiza según las marcas de compilación actuales.
Si especificas config_settings, se anulan los valores de las opciones de línea de comandos especificadas. (Las opciones no especificadas conservarán sus valores de la línea de comandos real).
En el diccionario config_settings especificado, las marcas de línea de comandos deben tener el prefijo de un valor de marcador de posición especial //command_line_option:, como se muestra antes.
Validar artefactos
Las principales formas de comprobar que los archivos generados sean correctos son las siguientes:
Puedes escribir una secuencia de comandos de prueba en shell, en Python o en otro lenguaje, y crear un destino del tipo de regla
*_testadecuado.Puedes usar una regla especializada para el tipo de prueba que quieras realizar.
Cómo usar un destino de prueba
La forma más directa de validar un artefacto es escribir una secuencia de comandos y agregar un destino *_test a tu archivo BUILD. Los artefactos específicos que deseas verificar deben ser dependencias de datos de este destino. Si la lógica de validación se puede reutilizar en varias pruebas, debe ser una secuencia de comandos que tome argumentos de línea de comandos controlados por el atributo args del destino de la prueba. A continuación, se muestra un ejemplo que valida que el resultado de myrule anterior sea "abc".
//mypkg/myrule_validator.sh:
if [ "$(cat $1)" = "abc" ]; then
echo "Passed"
exit 0
else
echo "Failed"
exit 1
fi
//mypkg/BUILD:
...
myrule(
name = "mytarget",
)
...
# Needed for each target whose artifacts are to be checked.
sh_test(
name = "validate_mytarget",
srcs = [":myrule_validator.sh"],
args = ["$(location :mytarget.out)"],
data = [":mytarget.out"],
)
Usa una regla personalizada
Una alternativa más complicada es escribir la secuencia de comandos de shell como una plantilla de la que se cree una instancia con una regla nueva. Esto implica más indirección y lógica de Starlark, pero genera archivos BUILD más limpios. Como beneficio secundario, cualquier procesamiento previo de argumentos se puede realizar en Starlark en lugar de en la secuencia de comandos, y esta se documenta un poco más, ya que usa marcadores de posición simbólicos (para sustituciones) en lugar de numéricos (para argumentos).
//mypkg/myrule_validator.sh.template:
if [ "$(cat %TARGET%)" = "abc" ]; then
echo "Passed"
exit 0
else
echo "Failed"
exit 1
fi
//mypkg/myrule_validation.bzl:
def _myrule_validation_test_impl(ctx):
"""Rule for instantiating myrule_validator.sh.template for a given target."""
exe = ctx.outputs.executable
target = ctx.file.target
ctx.actions.expand_template(output = exe,
template = ctx.file._script,
is_executable = True,
substitutions = {
"%TARGET%": target.short_path,
})
# This is needed to make sure the output file of myrule is visible to the
# resulting instantiated script.
return [DefaultInfo(runfiles=ctx.runfiles(files=[target]))]
myrule_validation_test = rule(
implementation = _myrule_validation_test_impl,
attrs = {"target": attr.label(allow_single_file=True),
# You need an implicit dependency in order to access the template.
# A target could potentially override this attribute to modify
# the test logic.
"_script": attr.label(allow_single_file=True,
default=Label("//mypkg:myrule_validator"))},
test = True,
)
//mypkg/BUILD:
...
myrule(
name = "mytarget",
)
...
# Needed just once, to expose the template. Could have also used export_files(),
# and made the _script attribute set allow_files=True.
filegroup(
name = "myrule_validator",
srcs = [":myrule_validator.sh.template"],
)
# Needed for each target whose artifacts are to be checked. Notice that you no
# longer have to specify the output file name in a data attribute, or its
# $(location) expansion in an args attribute, or the label for the script
# (unless you want to override it).
myrule_validation_test(
name = "validate_mytarget",
target = ":mytarget",
)
Como alternativa, en lugar de usar una acción de expansión de plantillas, podrías haber integrado la plantilla en el archivo .bzl como una cadena y haberla expandido durante la fase de análisis con el método str.format o con el formato %.
Prueba las utilidades de Starlark
Se puede usar el framework unittest.bzl de Skylib para probar funciones de utilidad (es decir, funciones que no son macros ni implementaciones de reglas). En lugar de usar la biblioteca analysistest de unittest.bzl, se puede usar unittest. Para estos paquetes de pruebas, se puede usar la función de conveniencia unittest.suite() a fin de reducir el código estándar.
//mypkg/myhelpers.bzl:
def myhelper():
return "abc"
//mypkg/myhelpers_test.bzl:
load("@bazel_skylib//lib:unittest.bzl", "asserts", "unittest")
load(":myhelpers.bzl", "myhelper")
def _myhelper_test_impl(ctx):
env = unittest.begin(ctx)
asserts.equals(env, "abc", myhelper())
return unittest.end(env)
myhelper_test = unittest.make(_myhelper_test_impl)
# No need for a test_myhelper() setup function.
def myhelpers_test_suite(name):
# unittest.suite() takes care of instantiating the testing rules and creating
# a test_suite.
unittest.suite(
name,
myhelper_test,
# ...
)
//mypkg/BUILD:
load(":myhelpers_test.bzl", "myhelpers_test_suite")
myhelpers_test_suite(name = "myhelpers_tests")
Para obtener más ejemplos, consulta las pruebas de Skylib.