Saltar a contenido

Escribe, ejecuta y prueba código

Para corregir un defecto o implementar una característica, requerirá escribir algún código nuevo.

Para empezar a trabajar en el código, asegúrate de tener un entorno de desarrollo configurado, y de estar trabajando en una rama

Contamos con una guía de estilo de código que describe nuestras directrices para escribir código para BeeWare.

Desarrollo dirigido en pruebas

Una buena forma de asegurarte de que tu código va a funcionar como esperas es escribir primero un caso de prueba para comprobarlo. Este caso de prueba debería fallar al principio, ya que el código que se está probando aún no existe. A continuación, puedes introducir los cambios necesarios en el código para que la prueba pase, y así saber que lo que has escrito resuelve el problema tal y como esperabas.

Ejecuta tu código

Una vez escrito el código, debes asegurarte que funciona. Tendrás que ejecutarlo manualmente para comprobar que hace lo que esperas. Si aún no lo has hecho, te conviene escribir un caso de prueba para tus cambios; como se ha mencionado anteriormente, esta prueba debería fallar si el código está comentado o no está presente.

Añadirás tu caso de prueba al conjunto de pruebas, para que se pueda ejecutar junto con el resto de pruebas. El siguiente paso es ejecutar el conjunto de pruebas.

Ejecución de pruebas y cobertura

BeeWare utiliza tox para gestionar el proceso de pruebas y pytest para su propio conjunto de pruebas.

El comando tox predeterminado incluye ejecutar:

  • ganchos de pre-commit
  • towncrier emite nota de comprobante

  • relaciona la documentación

  • conjunto de pruebas para las versiones disponibles de Python

  • informes de cobertura de código

Esto es esencialmente que ejecuta IC cuando envías una solicitud de Incorporación de Cambios.

Para ejecutar el conjunto completo de pruebas, ejecuta:

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

La ejecución del conjunto completo de pruebas puede tardar un rato. Puedes acelerarla considerablemente ejecutando tox en paralelo, es decir, ejecutando tox p (o tox run-parallel). Cuando ejecutes el conjunto de pruebas en paralelo, recibirás menos información sobre el progreso de las pruebas mientras se ejecutan, pero al final de la ejecución seguirás obteniendo un resumen de los problemas detectados. Deberías ver algún mensaje que indique que se han ejecutado las pruebas. Es posible que veas pruebas de tipo SKIPPED, pero nunca deberías obtener resultados de pruebas FAIL o ERROR. Ejecutamos nuestro conjunto completo de pruebas antes de fusionar cada parche. Si ese proceso detecta algún problema, no fusionamos el parche. Si encuentras un error o fallo en las pruebas, o bien hay algo extraño en tu entorno de pruebas, o bien has encontrado un caso extremo que no habíamos visto antes; en cualquier caso, ¡háznoslo saber!

Además de las pruebas que se superen, esto debería indicar una cobertura de pruebas del 100%.

Ejecución de variantes de pruebas

Ejecutar pruebas para múltiples versiones de Python

Por defecto, muchos de los comandos de tox intentarán ejecutar el conjunto de pruebas varias veces, una vez por cada versión de Python compatible con BeeWare. Sin embargo, para ello, cada una de las versiones de Python debe estar instalada en tu equipo y estar disponible para el proceso de [detección]tox de Python de (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). En general, si una versión de Python está disponible a través de la ruta en PATH, entonces tox debería poder encontrarla y utilizarla.

Ejecuta solo el conjunto de pruebas

Si estás realizando iteraciones rápidas en una nueva prestación, no es necesario que ejecutes el conjunto completo de pruebas; puedes ejecutar solo las pruebas unitarias. Para ello, ejecuta:

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Ejecutar un subconjunto de pruebas

Por defecto, tox ejecutará todas las pruebas del conjunto de pruebas unitarias. Cuando estés desarrollando una nueva prueba, puede resultarte útil ejecutar solo esa prueba. Para ello, puedes pasar cualquier especificador de pytest como argumento a tox. Estas rutas de pruebas son relativas al directorio briefcase. Por ejemplo, para ejecutar solo las pruebas de un único archivo, escribe:

(.venv) $ tox -e py -- tests/ruta_a_prueba_archivo/prueba_algún_test.py

(.venv) $ tox -e py -- tests/ruta_a_prueba_archivo/prueba_algún_test.py

(.venv) C:\...>tox -e py -- tests/ruta_archivo_test/prueba_algún_testpy

Seguirás obteniendo un informe de cobertura al ejecutar una parte del conjunto de pruebas, pero los resultados de cobertura solo incluirán las líneas de código que se hayan ejecutado en las pruebas concretas que hayas ejecutado.

Ejecuta el conjunto de pruebas para una versión concreta de Python

Por defecto, tox -e py se ejecutará utilizando el intérprete que se identifique como python en tu equipo. Si tienes varias versiones de Python instaladas y deseas probar una versión concreta de entre las que tienes instaladas, puedes especificar la versión de Python que deseas utilizar. Por ejemplo, para ejecutar el conjunto de pruebas en Python 3.10, escribe:

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

Se puede ejecutar un subconjunto de pruebas añadiendo -- y una especificación de prueba a la línea de comandos.

Ejecuta el conjunto de pruebas sin cobertura (rápido)

De forma predeterminada, tox ejecutará el conjunto de pruebas de pytest en modo de un solo subproceso. Puedes acelerar la ejecución del conjunto de pruebas ejecutándolo en paralelo. Este modo no genera archivos de cobertura debido a las dificultades que entraña capturar la cobertura dentro de los procesos generados. Para ejecutar una sola versión de Python en modo «rápido», ejecuta:

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

Se puede ejecutar un subconjunto de pruebas añadiendo -- y una especificación de prueba a la línea de comandos; se puede utilizar una versión específica de Python añadiendo la versión al objetivo de la prueba (por ejemplo, py310-fast para ejecutar fast en Python 3.10).

Cobertura del código

BeeWare mantiene una cobertura de ramas del 100 % en su código fuente. Cuando añadas o modifiques código en el proyecto, debes añadir código de prueba para garantizar la cobertura de cualquier cambio que realices.

Sin embargo, BeeWare está diseñado para múltiples plataformas, así como para múltiples versiones de Python, por lo que no es posible verificar la cobertura completa en una sola plataforma y versión de Python. Para solucionar esto, se definen varias reglas de cobertura condicionales en la sección tool.coverage.coverage_conditional_plugin.rules de pyproject.toml (por ejemplo, no-cover-if-is-windows se puede utilizar para marcar un bloque de código que no se ejecutará al ejecutar el conjunto de pruebas en Windows). Estas reglas se utilizan para identificar secciones de código que solo están cubiertas en plataformas o versiones de Python concretas.

Cabe destacar que la generación de informes de cobertura entre distintas versiones de Python puede presentar algunas peculiaridades. Por ejemplo, si los archivos de cobertura se generan con una versión de Python, pero el informe se elabora con otra, este puede incluir falsos positivos relativos a ramificaciones omitidas. Por este motivo, para generar los informes de cobertura siempre se debe utilizar la versión más antigua de Python empleada para crear los archivos de cobertura.

Interpretación de los resultados de la cobertura

Al final de la salida de la prueba de cobertura debería aparecer un informe con los datos de cobertura recopilados:

Nombre    Estados   Sucursal de referencia   Parte de la sucursal   Cobertura   Falta
 ---------------------------------------------------
 TOTAL    7540 0   1040 0  100,0 %

Esto nos indica que el conjunto de pruebas ha ejecutado todas las ramificaciones posibles del código. Aunque esto no garantiza al 100 % que no haya errores, sí significa que estamos probando cada línea de código del código fuente.

Si realizas cambios en el código, es posible que se produzca una brecha en esta cobertura. Cuando esto ocurra, el informe de cobertura te indicará qué líneas no se están ejecutando. Por ejemplo, supongamos que hemos realizado un cambio en some/interesting_file.py, añadiendo nueva lógica. El informe de cobertura podría tener un aspecto similar al siguiente:

Name                                                                  Stmts   Miss Rama BrPart  Cobertura   Ausencia
 -------------------------------------------------------------------------------
 src/algún/archivo_interesante.py           111      1     26      0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 TOTAL                                                                 7540      1   1726      0  99'9%

Esto nos indica que la línea 170, las líneas 302-307 y una ramificación que salta de la línea 320 a la línea 335 no están siendo ejecutadas por el conjunto de pruebas. Tendrás que añadir nuevas pruebas (o modificar una ya existente) para restablecer esta cobertura.

Informe de cobertura para la plataforma de ejecución y la versión de Python

Puedes generar un informe de cobertura para tu plataforma y versión de Python. Por ejemplo, para ejecutar el conjunto de pruebas y generar un informe de cobertura en Python 3.10, ejecuta:

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Informe de cobertura para la plataforma de alojamiento

Si todas las versiones compatibles de Python están disponibles para tox, se puede generar un informe de cobertura para la plataforma de host ejecutando:

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Informes de cobertura en HTML

Se puede generar un informe de cobertura HTML añadiendo -html a cualquiera de los nombres de entorno de cobertura tox, por ejemplo:

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

¡No se trata solo de escribir pruebas!

Aunque nos aseguramos de probar todo nuestro código, la tarea no consiste solo en mantener ese nivel de pruebas. Parte de la tarea consiste en revisar el código sobre la marcha. Se podría escribir un conjunto completo de pruebas para un chaleco salvavidas de hormigón… ¡pero un chaleco salvavidas de hormigón seguiría siendo inútil para el fin al que está destinado!

A medida que desarrolles pruebas, debes comprobar también que el módulo principal sea coherente internamente. Si detectas algún nombre de método que no sea coherente internamente (por ejemplo, algo que se llame on_select en un módulo, pero on_selected en otro), o en el que los datos no se gestionen de forma coherente, márcalo y avísanos creando un ticket. O, si estás seguro de saber qué hay que hacer, crea una solicitud de incorporación de cambios que solucione el problema que has encontrado.

Una vez que todo funcione, puedes enviar una solicitud de extracción con tus cambios.