Django viene con una suite de pruebas propia, en el directorio tests del código base. Es nuestra política asegurarnos de que todas las pruebas pasen siempre.
Apreciamos cualquier y toda contribución a la suite de pruebas!
Las pruebas Django utilizan todos la infraestructura de prueba que viene con Django para probar aplicaciones. Consulte Escribir y ejecutar pruebas para una explicación de cómo escribir nuevas pruebas.
Primero, fork Django en GitHub.
Segundo, crea y activa un entorno virtual. Si no estás familiarizado con cómo hacer eso, lee nuestro tutorial de contribución.
A continuación, clona tu fork, instala algunas dependencias y ejecuta las pruebas:
$ git clone https://github.com/YourGitHubName/django.git django-repo
$ cd django-repo/tests
$ python -m pip install -e ..
$ python -m pip install -r requirements/py3.txt
$ ./runtests.py
Instalar los requisitos puede requerir algunos paquetes del sistema operativo que tu computadora no tiene instalados. Puedes averiguar qué paquete instalar haciendo una búsqueda en la web con la última línea o así del mensaje de error. Intenta agregar tu sistema operativo a la consulta si es necesario.
Si tienes problemas para instalar los requisitos, puedes saltarte ese paso. Consulta Ejecutar todos los tests para obtener detalles sobre la instalación de las dependencias de pruebas opcionales. Si no tienes una dependencia opcional instalada, se saltarán las pruebas que la requieren.
Ejecutar las pruebas requiere un módulo de configuración Django que defina los datos bases a utilizar. Para ayudarte a empezar, Django proporciona y utiliza un módulo de configuración de ejemplo que utiliza el motor de base de datos SQLite. Consulta Usando otro módulo settings para aprender cómo utilizar un módulo de configuración diferente para ejecutar las pruebas con una base de datos distinta.
¿Tienes problemas? Consulta Solución de problemas para resolver algunos problemas comunes.
tox¶Tox es una herramienta para ejecutar pruebas en diferentes entornos virtuales. Django incluye un archivo tox.ini básico que automatiza algunas comprobaciones que nuestro servidor de compilación realiza en solicitudes de pull. Para ejecutar las pruebas unitarias y otras comprobaciones (como import sorting, la comprobadora de ortografía del documento y la formateo de código), instala y ejecuta el comando tox desde cualquier lugar del árbol fuente de Django:
$ python -m pip install tox
$ tox
Por defecto, tox ejecuta el conjunto de pruebas con el archivo de configuración de pruebas bundlado para SQLite, black, blacken-docs, flake8, isort, zizmor y la comprobadora de ortografía del documento. Además de las dependencias del sistema mencionadas en otras partes de esta documentación, el comando python3 debe estar en tu ruta y vinculado a la versión adecuada de Python. Una lista de entornos por defecto se puede ver de la siguiente manera:
$ tox -l
py3
black
blacken-docs
flake8>=3.7.0
docs
isort>=7.0.0
zizmor>=1.16.3
Además de los entornos por defecto, tox admite ejecutar pruebas unitarias para otras versiones de Python y otros motores de base de datos. Dado que el conjunto de pruebas de Django no incluye un archivo de configuración de pruebas para motores de base de datos distintos del SQLite, sin embargo, debes crear y proporcionar tu propio archivo de configuración de pruebas. Por ejemplo, para ejecutar las pruebas con Python 3.10 utilizando PostgreSQL:
$ tox -e py310-postgres -- --settings=my_postgres_settings
Este comando configura un entorno virtual de Python 3.10, instala las dependencias del conjunto de pruebas de Django (incluyendo las para PostgreSQL) y llama a runtests.py con los argumentos proporcionados (en este caso, --settings=my_postgres_settings).
La documentación de Django en español es la siguiente:
Tox también respeta la variable de entorno DJANGO_SETTINGS_MODULE, si está configurada. Por ejemplo, lo siguiente es equivalente al comando anterior:
$ DJANGO_SETTINGS_MODULE=my_postgres_settings tox -e py310-postgres
Los usuarios de Windows deben utilizar:
...\> set DJANGO_SETTINGS_MODULE=my_postgres_settings
...\> tox -e py310-postgres
Django incluye un conjunto de pruebas unitarias de JavaScript para funciones en ciertas aplicaciones contrib. Las pruebas de JavaScript no se ejecutan por defecto utilizando tox porque requieren que esté instalado Node.js y no son necesarias para la mayoría de las actualizaciones. Para ejecutar las pruebas de JavaScript utilizando tox:
$ tox -e javascript
Este comando ejecuta npm install para asegurarse de que los requisitos de prueba están actualizados y luego ejecuta npm test.
django-docker-box¶django-docker-box permite ejecutar la suite de pruebas de Django en todas las bases de datos admitidas y versiones de Python. Consulte la página del proyecto django-docker-box para obtener instrucciones de instalación y uso.
settings¶El módulo de configuración incluido (tests/test_sqlite.py) permite ejecutar la suite de pruebas utilizando SQLite. Si deseas ejecutar las pruebas con una base de datos diferente, necesitarás definir tu propio archivo de configuración. Algunas pruebas, como las de contrib.postgres, son específicas de un backend de base de datos particular y se saltarán si se ejecutan con un backend diferente. Algunas pruebas se saltan o son fallas esperadas en un backend de base de datos particular (consulte DatabaseFeatures.django_test_skips y DatabaseFeatures.django_test_expected_failures en cada backend).
Para ejecutar las pruebas con diferentes configuraciones, asegúrate de que el módulo esté en tu PYTHONPATH y pasa el módulo con –settings.
La configuración DATABASES en cualquier módulo de configuración para pruebas necesita definir dos bases de datos:
Una base de datos por defecto. Esta base de datos debería utilizar el motor que desee utilizar para las pruebas primarias.
Una base de datos con el alias other. La base de datos other se utiliza para probar que las consultas pueden dirigirse a bases de datos diferentes. Esta base de datos debe utilizar el mismo back-end que la default, y debe tener un nombre diferente.
Si estás utilizando un back-end que no es SQLite, necesitarás proporcionar otros detalles para cada base de datos:
La opción USER necesita especificar una cuenta de usuario existente para la base de datos. Ese usuario necesita permiso para ejecutar CREATE DATABASE para que se pueda crear la base de datos de prueba.
La opción PASSWORD necesita proporcionar la contraseña para el USER que se ha especificado.
Las bases de datos de prueba obtienen su nombre al agregar test_ al valor de la configuración NAME para las bases de datos definidas en DATABASES. Estas bases de datos de prueba se eliminan cuando los tests finalizan.
También debes asegurarte de que tu base de datos utilice UTF-8 como conjunto de caracteres predeterminado. Si el servidor de bases de datos no utiliza UTF-8 como conjunto de caracteres por defecto, necesitarás incluir un valor para CHARSET en el diccionario de configuración de pruebas para la base de datos aplicable.
Django’s entire test suite takes a while to run, y ejecutar cada prueba individual podría ser redundante si, por ejemplo, solo agregaste una prueba a Django que deseas ejecutar rápidamente sin ejecutar todo lo demás. Puedes ejecutar un subconjunto de las pruebas unitarias mediante la inclusión de los nombres de los módulos de prueba en runtests.py en la línea de comandos.
Por ejemplo, si deseas ejecutar solo las pruebas para relaciones genéricas e internacionalización, escribe:
$ ./runtests.py --settings=path.to.settings generic_relations i18n
¿Cómo encuentras el nombre de cada prueba individual? Busca en tests/ — cada nombre de directorio allí es el nombre de una prueba.
Si deseas ejecutar solo una clase particular de pruebas, puedes especificar una lista de rutas a clases de prueba individuales. Por ejemplo, para ejecutar las pruebas TranslationTests del módulo i18n, escribe:
$ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests
Puedes ir más allá y especificar un método de prueba individual de esta manera:
$ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests.test_lazy_objects
Puedes ejecutar pruebas comenzando en un módulo de nivel superior especificado con la opción --start-at. Por ejemplo:
$ ./runtests.py --start-at=wsgi
También puedes ejecutar pruebas después de un módulo de nivel superior especificado con la opción --start-after. Por ejemplo:
$ ./runtests.py --start-after=wsgi
Ten en cuenta que la opción --reverse no impacta en las opciones --start-at o --start-after. Además, estas opciones no pueden usarse con etiquetas de prueba.
Algunas pruebas requieren Selenium y un navegador web. Para ejecutar estas pruebas, debes instalar el paquete selenium y ejecutar las pruebas con la opción --selenium=<BROWSERS>. Por ejemplo, si tienes Firefox e Internet Explorer instalados:
$ ./runtests.py --selenium=firefox,chrome
Veamos las traducciones:
Especificar --selenium establece automáticamente --tags=selenium para ejecutar solo los tests que requieren selenium.
Algunos navegadores (por ejemplo, Chrome o Firefox) admiten pruebas sin cabeza, lo que puede ser más rápido y estable. Agrega la opción --headless para habilitar este modo.
Para probar cambios en la interfaz administrativa, los tests de selenium se pueden ejecutar con la opción --screenshots habilitada. Las capturas de pantalla se guardarán en el directorio tests/screenshots/.
Para definir cuándo deben tomarse las capturas de pantalla durante un test de selenium, la clase del test debe utilizar el decorador @django.test.selenium.screenshot_cases con una lista de tipos de captura de pantalla admitidos ("desktop_size", "mobile_size", "small_screen_size", "rtl", "dark", y "high_contrast"). Luego puede llamar a self.take_screenshot("nombre-único-de-captura") en el punto deseado para generar las capturas de pantalla. Por ejemplo:
from django.test.selenium import SeleniumTestCase, screenshot_cases
from django.urls import reverse
class SeleniumTests(SeleniumTestCase):
@screenshot_cases(["desktop_size", "mobile_size", "rtl", "dark", "high_contrast"])
def test_login_button_centered(self):
self.selenium.get(self.live_server_url + reverse("admin:login"))
self.take_screenshot("login")
...
Esto genera varias capturas de pantalla de la página de inicio - una para una pantalla de escritorio, una para una pantalla móvil, una para idiomas de derecha a izquierda en escritorio, una para el modo oscuro en escritorio, y una para el modo contraste alto en escritorio cuando se utiliza chrome.
La opción --screenshots y el decorador @screenshot_cases fueron agregados.
Si deseas ejecutar la suite completa de tests, necesitarás instalar varias dependencias:
argon2-cffi 19.2.0+
asgiref 3.8.1+ (required)
colorama 0.4.6+
docutils 0.19+
Jinja2 2.11+
Pillow 6.2.1+
redis 3.4+
pymemcache, plus a supported Python binding
selenium 4.8.0+
sqlparse 0.3.1+ (requerido)
tblib 1.5.0+
Puedes encontrar estas dependencias en los archivos de requisitos de pip dentro del directorio tests/requirements del árbol de fuentes de Django y las instalar como se indica a continuación:
$ python -m pip install -r tests/requirements/py3.txt
Si encuentras un error durante la instalación, es posible que tu sistema esté faltando una dependencia para uno o más de los paquetes Python. Consulta la documentación del paquete que falló o busca en Internet con el mensaje de error que encuentres.
También puedes instalar el adaptador de base de datos de tu elección utilizando oracle.txt, mysql.txt o postgres.txt.
Si deseas probar los backends de caché memcached o Redis, también necesitarás definir una configuración CACHES que apunte a tu instancia de memcached o Redis respectivamente.
Para ejecutar las pruebas de GeoDjango, necesitarás configurar una base de datos espacial e instalar los bibliotecas geoespaciales.
Cada una de estas dependencias es opcional. Si te falta alguna de ellas, las pruebas asociadas se saltarán.
Para ejecutar algunas de las pruebas de autoreload, necesitarás instalar el servicio Watchman.
Se anima a los contribuyentes a correr la cobertura en el conjunto de pruebas para identificar áreas que necesitan pruebas adicionales. La instalación y uso de la herramienta de cobertura se describen en cobertura del código.
Para ejecutar la cobertura en el conjunto de pruebas de Django utilizando los ajustes de prueba estándar:
$ coverage run ./runtests.py --settings=test_sqlite
Después de ejecutar la cobertura, combina todas las estadísticas de cobertura ejecutando:
$ coverage combine
Después de generar el informe HTML ejecutando:
$ coverage html
Al ejecutar la cobertura para las pruebas Django, el archivo de configuración incluido .coveragerc define coverage_html como directorio de salida del informe y también excluye varios directorios no relevantes para los resultados (código de prueba o código externo incluido en Django).
Las pruebas para las aplicaciones contribuyentes se pueden encontrar en el directorio tests/, típicamente bajo <app_name>_tests. Por ejemplo, las pruebas para contrib.auth están ubicadas en tests/auth_tests.
main¶Asegúrate de tener la última versión puntual de una versión de Python soportada, ya que hay a menudo bugs en versiones anteriores que pueden causar que la suite de pruebas se quede colgada o falle.
En macOS (High Sierra y versiones posteriores), es posible ver este mensaje registrado, después del cual las pruebas se quedan colgadas:
objc[42074]: +[__NSPlaceholderDate initialize] may have been in progress in
another thread when fork() was called.
Para evitar esto, establece la variable de entorno OBJC_DISABLE_INITIALIZE_FORK_SAFETY, por ejemplo:
$ OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES ./runtests.py
O agrega export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES a tu archivo de inicio del shell (por ejemplo, ~/.profile).
UnicodeEncodeError¶Si el paquete locales no está instalado, algunas pruebas fallarán con un UnicodeEncodeError.
Puedes resolver esto en sistemas basados en Debian, por ejemplo, ejecutando:
$ apt-get install locales
$ dpkg-reconfigure locales
Puedes resolver esto para sistemas macOS configurando la localización de tu shell:
$ export LANG="en_US.UTF-8"
$ export LC_ALL="en_US.UTF-8"
Ejecuta el comando locale para confirmar el cambio. Opcionalmente, agrega esas comandos export a tu archivo de inicio de la terminal (por ejemplo, ~/.bashrc para Bash) para evitar tener que retipiarlos.
En caso de que una prueba pase cuando se ejecuta de forma aislada pero falle dentro del conjunto completo de pruebas, tenemos algunas herramientas para ayudar a analizar el problema.
La opción --bisect del comando runtests.py ejecutará la prueba fallida mientras se reduce en la mitad el conjunto de pruebas con las que se ejecuta en cada iteración, lo que a menudo hace posible identificar un pequeño número de pruebas que pueden estar relacionadas con la falla.
Por ejemplo, supongamos que la prueba fallida que funciona por sí sola es ModelTest.test_eq, entonces utilizando:
$ ./runtests.py --bisect basic.tests.ModelTest.test_eq
intentará determinar una prueba que interfiera con la dada. Primero, se ejecuta la prueba con la primera mitad del conjunto de pruebas. Si ocurre una falla, la primera mitad del conjunto de pruebas se divide en dos grupos y cada grupo se ejecuta con la prueba especificada. Si no hay fallas con la primera mitad del conjunto de pruebas, el segundo conjunto de pruebas se ejecuta con la prueba especificada y se divide apropiadamente como se describe anteriormente. El proceso repite hasta que el conjunto de pruebas fallidas esté minimizado.
La traducción de los textos es la siguiente:
$ ./runtests.py --pair basic.tests.ModelTest.test_eq
irá en parejas con test_eq cada etiqueta de test.
Con tanto --bisect como --pair, si ya sospechas qué casos podrían ser responsables de la falla, puedes limitar los tests a que se analicen entre sí cruzadamente especificando más etiquetas de test después del primero:
$ ./runtests.py --pair basic.tests.ModelTest.test_eq queries transactions
También puedes intentar ejecutar cualquier conjunto de tests en un orden aleatorio o inverso utilizando las opciones --shuffle y --reverse. Esto puede ayudarte a verificar si ejecutar los tests en un orden diferente no causa ningún problema:
$ ./runtests.py basic --shuffle
$ ./runtests.py basic --reverse
Si deseas examinar el SQL que se está ejecutando en los tests fallidos, puedes activar la regulación de SQL utilizando la opción --debug-sql. Si combinás esto con --verbosity=2, todas las consultas SQL se mostrarán:
$ ./runtests.py basic --debug-sql
Por defecto, los tests se ejecutan en paralelo con un proceso por núcleo. Sin embargo, cuando los tests se ejecutan en paralelo, solo verás un traceback truncado para cualquier falla en un test. Puedes ajustar este comportamiento con la opción --parallel:
$ ./runtests.py basic --parallel=1
También puedes utilizar el DJANGO_TEST_PROCESSES variable de entorno para este propósito.
Para evitar contaminar el registro global de apps y prevenir la creación innecesaria de tablas, los modelos definidos en un método de prueba deben estar ligados a una instancia temporal Apps. Para hacer esto, utilice el decorador isolate_apps():
from django.db import models
from django.test import SimpleTestCase
from django.test.utils import isolate_apps
class TestModelDefinition(SimpleTestCase):
@isolate_apps("app_label")
def test_model_definition(self):
class TestModel(models.Model):
pass
...
Estableciendo app_label
Los modelos definidos en un método de prueba sin etiqueta explícita de app_label se asignan automáticamente la etiqueta del paquete en el que está ubicado su clase de prueba.
Para asegurarse de que los modelos definidos dentro del contexto de las instancias de isolate_apps() estén correctamente instalados, debe pasar la serie de etiquetas app_label como argumentos:
tests/app_label/tests.py¶from django.db import models
from django.test import SimpleTestCase
from django.test.utils import isolate_apps
class TestModelDefinition(SimpleTestCase):
@isolate_apps("app_label", "other_app_label")
def test_model_definition(self):
# This model automatically receives app_label='app_label'
class TestModel(models.Model):
pass
class OtherAppModel(models.Model):
class Meta:
app_label = "other_app_label"
...
may 31, 2026