Prueba

Informar un problema Ver fuente

Existen varios enfoques diferentes para probar el código de Starlark en Bazel. En esta página, se recopilan los frameworks y las prácticas recomendadas actuales por caso de uso.

Prueba reglas

Skylib tiene un framework de prueba llamado unittest.bzl para verificar el comportamiento de las reglas en el tiempo de análisis, como sus acciones y proveedores. Estas se denominan "pruebas de análisis" y, en la actualidad, son la mejor opción para probar el funcionamiento interno de las reglas.

Ten en cuenta las siguientes advertencias:

  • Las aserciones de prueba ocurren dentro de la compilación, no en un proceso independiente del ejecutor de pruebas. Los destinos que crea la prueba deben tener un nombre de modo que no coincidan con los objetivos de otras pruebas o de la compilación. Bazel considera un error que ocurre durante la prueba como una falla de la compilación en lugar de una falla de prueba.

  • Se requiere una buena cantidad de código estándar para configurar las reglas de prueba y las que contienen las aserciones de prueba. Al principio, esta plantilla puede parecer abrumadora. Es útil tener en cuenta que las macros se evalúan y los destinos se generan durante la fase de carga, mientras que las funciones de implementación de reglas no se ejecutan hasta más adelante, durante la fase de análisis.

  • Las pruebas de análisis están diseñadas para ser relativamente pequeñas y livianas. Ciertas funciones del framework de pruebas de análisis están restringidas a la verificación de objetivos con una cantidad máxima de dependencias transitivas (actualmente, 500). Esto se debe a las implicaciones de rendimiento que tiene usar 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 da 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 fallas, no se generan de inmediato mediante una llamada 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 uno que verifica 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 declaraciones load() iniciales, el archivo tiene dos partes principales:

  • Las pruebas en sí, cada una de las cuales consiste en 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 los casos de prueba, es posible que varios casos de prueba compartan 1) y 2).

  • La función del paquete de pruebas, que llama a las funciones de tiempo de carga de cada prueba y declara un destino test_suite que agrupa todas las pruebas.

Para mantener la coherencia, sigue la convención de nombres recomendada: deja que foo represente 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 JUnit se llamaría testFoo.

Luego, haz lo siguiente:

  • la macro que genera la prueba y el destino en prueba debe llamarse _test_foo (_test_provider_contents).

  • su 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 en prueba 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 etiquetas en el mismo paquete de COMPILACIÓN, por lo que es útil usar un nombre único para la prueba.

Pruebas de fallas

Puede ser útil verificar que una regla falla en determinadas entradas o en ciertos estados. Esto se puede hacer con el framework 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 reglas 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úrese de que la orientación que se está probando esté etiquetada 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 mostrará un error 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.

Cómo verificar las acciones registradas

Se recomienda escribir pruebas que realicen aserciones sobre las acciones que registra tu regla, por ejemplo, con 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 objetivo que se está probando.

Verifica el comportamiento de las reglas con diferentes marcas

Te recomendamos que verifiques que tu regla real se comporta de una manera determinada en función de determinadas marcas de compilación. Por ejemplo, es posible que tu regla se comporte 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 a prueba con las marcas de compilación deseadas:

bazel test //mypkg:myrules_test -c opt

Sin embargo, es imposible que el conjunto de pruebas contenga simultáneamente una prueba que verifique el comportamiento de la regla en -c opt y otra que verifique el comportamiento de la regla en -c dbg. Ninguna de las dos pruebas podría ejecutarse 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, un destino en prueba 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 de 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 arriba.

Valida artefactos

Las principales formas de comprobar que tus archivos generados son correctos son las siguientes:

  • Puedes escribir una secuencia de comandos de prueba en shell, Python o algún otro lenguaje, y crear un destino del tipo de regla *_test adecuado.

  • Puedes usar una regla especializada para el tipo de prueba que quieres realizar.

Usa 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, debería ser una secuencia de comandos que tome argumentos de la línea de comandos controlados por el atributo args del destino de prueba. Este es 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"],
)

Cómo usar una regla personalizada

Una alternativa más compleja es escribir la secuencia de comandos de shell como una plantilla para la que una regla nueva cree una instancia. Esto implica más indirección y lógica de Starlark, pero genera archivos BUILD más limpios. Como beneficio adicional, cualquier procesamiento previo de argumentos se puede realizar en Starlark en lugar de la secuencia de comandos, y esta última se documenta mejor, 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 intercalado 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 %.

Cómo probar las utilidades de Starlark

El framework unittest.bzl de Skylib se puede usar para probar funciones de utilidad (es decir, funciones que no son implementaciones de macros ni de reglas). En lugar de usar la biblioteca analysistest de unittest.bzl, se puede usar unittest. Para estos conjuntos de pruebas, se puede usar la función conveniente 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 propias pruebas de Skylib.