..
.. META INFORMATION OF TRANSLATION
..
..   $TranslationStatus: Done, waiting for revision. $
..   $OriginalRevision: 11268 $
..   $TranslationAuthors: Luiz Fernando Barbosa Vital, Robson Mendonça $
..
.. INFO OF THIS FILE (DO NOT EDIT! UPDATED BY SUBVERSION)
..
..   $HeadURL$
..   $LastChangedRevision$
..   $LastChangedBy$
..   $LastChangedDate$
..

==========================
Testando aplicações Django
==========================

.. module:: django.test
   :synopsis: Ferramentas de teste de aplicações Django.

O teste automatizado é uma ferramenta extremamente útil para eliminar bugs
utilizada pelo desenvolvedor Web moderno. Você pode usar uma coleção de testes
-- uma **test suite** -- para resolver, ou evitar, vários problemas:

    * Quando você está escrevendo um código novo, pode usar os testes para
      verificar se seu código funciona como esperado.

    * Quando está refatorando ou modificando um código antigo, você pode usar os
      testes para garantir que suas mudanças não afetaram inesperadamente o
      comportamento de sua aplicação.

Testar uma aplicação Web é uma tarefa complexa, porque uma aplicação Web é
feita de várias camadas de lógica -- da manipulação de uma requisição em nível
HTTP, para a validação e processamento de formulário, para a renderização de
template. Com o framework de teste-execução do Django e outros utilitários,
você pode simular requisições, inserir dados de teste, inspecionar a saída de
sua aplicação e freqüentemente verificar se seu código está fazendo o que
deveria.

A melhor parte é que isso tudo é muito fácil.

Este documento é dividido em duas duas seções. Na primeira, explicamos como
escrever testes com Django e, posteriormente, explicamos como rodá-los.

Escrevendo testes
=================

Existem duas maneiras de se escrever testes com Django, correspondendo com os
dois frameworks de teste que estão na biblioteca padrão do Python, que são:

    * **Unit tests** -- (Testes unitários) são testes que são expressados como
      métodos em uma classe Python que é uma subclasse de ``unittest.TestCase``.
      Por exemplo::

          import unittest

          class MyFuncTestCase(unittest.TestCase):
              def testBasic(self):
                  a = ['larry', 'curly', 'moe']
                  self.assertEquals(my_func(a, 0), 'larry')
                  self.assertEquals(my_func(a, 1), 'curly')
                  
    * **Doctests** -- os testes estão embutidos nas docstrings (strings de
      documentação) de suas funções e são escritas de tal maneira a emular uma
      sessão do interpretador interativo do Python. Por exemplo::

          def my_func(a_list, idx):
              """
              >>> a = ['larry', 'curly', 'moe']
              >>> my_func(a, 0)
              'larry'
              >>> my_func(a, 1)
              'curly'
              """
              return a_list[idx]

We'll discuss choosing the appropriate test framework later, however, most
experienced developers prefer unit tests. Você também pode usar
qualquer *outro* framework de testes Python, como explicaremos adiante.

Escrevendo testes unitários
---------------------------

Como doctests, os testes unitários do Django usam um módulo da biblioteca
padrão: unittest_. Esse módulo usa uma maneira diferente de definir testes,
utilizando um método baseado em classes.

.. admonition:: unittest2

    .. versionchanged:: 1.3

    Python 2.7 introduced some major changes to the unittest library,
    adding some extremely useful features. To ensure that every Django
    project can benefit from these new features, Django ships with a
    copy of unittest2_, a copy of the Python 2.7 unittest library,
    backported for Python 2.4 compatibility.

    To access this library, Django provides the
    ``django.utils.unittest`` module alias. If you are using Python
    2.7, or you have installed unittest2 locally, Django will map the
    alias to the installed version of the unittest library. Otherwise,
    Django will use it's own bundled version of unittest2.

    To use this alias, simply use::

        from django.utils import unittest

    wherever you would have historically used::

        import unittest

    If you want to continue to use the base unittest library, you can --
    you just won't get any of the nice new unittest2 features.

.. _unittest2: http://pypi.python.org/pypi/unittest2

Como nos doctests, para uma dada aplicação Django, o executor de testes procura
por testes unitários em dois lugares:

    * O arquivo ``models.py``. O executor de testes procura por qualquer
      subclasse de ``unittest.TestCase`` nesse módulo.

    * Um arquivo chamado ``tests.py`` no diretório da aplicação -- o mesmo que
      contém ``models.py``. Novamente, o executor de testes procura por
      qualquer subclasse de ``unittest.TestCase`` nesse módulo.

Este exemplo de subclasse de ``unittest.TestCase`` é equivalente ao exemplo
dado na seção de doctest acima::

    import unittest
    from myapp.models import Animal

    class AnimalTestCase(unittest.TestCase):
        def setUp(self):
            self.lion = Animal.objects.create(name="lion", sound="roar")
            self.cat = Animal.objects.create(name="cat", sound="meow")

        def testSpeaking(self):
            self.assertEquals(self.lion.speak(), 'The lion says "roar"')
            self.assertEquals(self.cat.speak(), 'The cat says "meow"')

Quando você :ref:`roda seus testes <running-tests>`, o comportamento padrão do
utilitário de teste é encontrar todos os test cases (ou seja, subclasses de
``unittest.TestCase``) nos arquivos ``models.py`` e ``tests.py``,
automaticamente montar uma test suite (conjunto de testes) destes test cases, e
rodá-la.

Há uma segunda maneira de se definir um test suite para um módulo: se você
define uma função chamada ``suite()`` seja em ``models.py`` ou ``tests.py``, o
executor de testes do Django usará essa função para construir a test suite para
o módulo. Isso segue a `organização sugerida`_ para testes unitários. Veja a
documentação do Python para mais detalhes de como construir uma test suite
complexa.

Para mais detalhes sobre ``unittest``, veja a `documentação de unittest da
biblioteca padrão`_.

.. _unittest: http://docs.python.org/lib/module-unittest.html
.. _documentação de unittest da biblioteca padrão: unittest_
.. _organização sugerida: http://docs.python.org/lib/organizing-tests.html

Escrevendo doctests
-------------------

Os doctests usam o módulo doctest_ padrão do Python, que procura em suas
docstrings por instruções que se pareçam com uma sessão do interpretador
interativo do Python. Uma explicação completa de como funciona o doctest está
fora do escopo deste documento; leia a documentação oficial do Python para
maiores detalhes.


.. admonition:: O que é uma **docstring**?

    Uma boa explicação de docstrings (e algumas diretrizes para utilizá-la
    de maneira completa) pode ser encontrada em :pep:`257`:

        Uma docstring é uma literal de string que ocorre como a primeira
        instrução em um módulo, função, classe, ou definição de método. Esta
        docstring torna-se o atributo especial ``__doc__`` do objeto em questão.

    Por exemplo, esta função possui uma docstring que descreve o que ela faz::

        def add_two(num):
            "Retorna o resultado da adição de dois ao número informado."
            return num + 2

    Pelo motivo de que testes freqüentemente geram uma boa documentação,
    colocar testes diretamente nas suas docstrings é uma maneira eficiente de
    documentar *e* testar o seu código.

Para uma dada aplicação Django, o executor de testes procura por doctests em
dois lugares:

    * No arquivo ``models.py``. Você pode definir doctests para o módulo todo
      e/ou um doctest para cada modelo. É uma pratica comum colocar doctests
      de nível de aplicação numa docstring do módulo e doctests de nível de
      modelo em docstrings de modelos.

    * Um arquivo chamado ``tests.py`` no diretório da aplicação -- ou seja, o
      diretório que contém ``models.py``. Esse arquivo é um ``hook`` para todos
      e quaisquer doctests que você queira escrever que não sejam
      necessariamente relacionados a modelos.

Aqui vai um exemplo de doctest de modelo::

    # models.py

    from django.db import models

    class Animal(models.Model):
        """
        An animal that knows how to make noise

        # Create some animals
        >>> lion = Animal.objects.create(name="lion", sound="roar")
        >>> cat = Animal.objects.create(name="cat", sound="meow")

        # Make 'em speak
        >>> lion.speak()
        'The lion says "roar"'
        >>> cat.speak()
        'The cat says "meow"'
        """
        name = models.CharField(max_length=20)
        sound = models.CharField(max_length=20)

        def speak(self):
            return 'The %s says "%s"' % (self.name, self.sound)


Quando você :ref:`roda seus testes <running-tests>`, o executor de testes irá
encontrar essa docstring -- note que pedaços dela parecem uma sessão interativa
de Python -- e executar suas linhas verificando se os resultados batem.

No caso de testes de modelo, note que o executor de testes cuida de criar seu
próprio banco de dados. Ou seja, qualquer teste que acesse banco de dados --
criando e gravando instâncias de modelos, por exemplo -- não afetará seu banco
de dados em produção. Cada doctest inicia com um banco de dados novo contendo
uma tabela vazia para cada modelo. (Veja a seção de fixtures, abaixo, para mais
detalhes.) Note que para usar esse recurso, o usuário que o Django utiliza para
se conectar ao banco de dados deve ter direito de criar novos bancos ``CREATE
DATABASE``.

Para mais detalhes sobre como funciona o doctest, veja a `documentação da
biblioteca padrão para doctest`_

.. _doctest: http://docs.python.org/lib/module-doctest.html
.. _documentação da biblioteca padrão para doctest: doctest_

Qual devo usar?
---------------

Pelo motivo de o Django suportar ambos os frameworks de testes padrão do
Python, cabe a você, de acordo com seu gosto, decidir qual utilizar. Você pode
até mesmo decidir usar *ambos*.

Para desenvolvedores novatos em testes, essa escolha pode parecer confusa. Aqui
estão algumas diferenças chave para ajudá-lo a decidir qual método é melhor:

    * Se você já utiliza Python por algum tempo, o ``doctest`` provavelmente
      parecerá mais "pythônico". Ele foi projetado para tornar a escrita de
      testes o mais fácil possível, então não requer nenhum esforço extra de
      escrever classes ou métodos. Você simplesmente coloca seus testes em
      docstrings. Isso tem a vantagem adicional de servir como documentação
      (e documentação correta!). However, while
      doctests are good for some simple example code, they are not very good if
      you want to produce either high quality, comprehensive tests or high
      quality documentation. Test failures are often difficult to debug
      as it can be unclear exactly why the test failed. Thus, doctests should
      generally be avoided and used primarily for documentation examples only.

    * O framework ``unittest`` provavelmente será bem familiar para
      desenvolvedores vindos do Java. O ``unittest`` é inspirado pelo JUnit
      do Java, então você se sentirá em casa com esse método se você já usou
      o JUnit ou qualquer outro framework de testes inspirado no JUnit.

    * Se você precisa escrever muitos testes que compartilham código parecido,
      então você vai gostar da organização baseada em classes e métodos do
      framework ``unittest``. Ele facilita abstrair tarefas comuns em métodos
      comuns. O framework também suporta configuração explícita e/ou
      limpeza de rotinas, que te dão um alto nível de controle sobre o ambiente
      no qual seus testes são executados.
      
    * If you're writing tests for Django itself, you should use ``unittest``.

.. _running-tests:

Rodando os testes
=================

Uma vez que você escreveu os testes, execute-os utilizando o utilitário do seu
projeto ``manage.py``::

    $ ./manage.py test

Por padrão, isso executará cada teste em cada aplicação em
:setting:`INSTALLED_APPS`. Se você só quer rodar os testes para uma aplicação em
particular, adicione o nome da aplicação à linha de comando. Por exemplo, se seu
:setting:`INSTALLED_APPS` contém ``'myproject.polls'`` e
``'myproject.animals'``, você pode rodar somente os testes unitários de
``myproject.animals`` com este comando::

    # ./manage.py test animals

Note que utilizamos ``animals``, e não ``myproject.animals``.

Se você utiliza testes unitários, em vez de doctests, você pode ser ainda *mais*
específico na escolha de quais testes executar. Para rodar um único teste em uma
aplicação (por exemplo, o ``AnimalTestCase`` descrito na seção "Escrevendo
testes unitários"), adicione o nome do test case à linha de comando::

    $ ./manage.py test animals.AnimalTestCase

E pode ficar ainda mais granular que isso! Para rodar um *único* método de
teste dentro de um test case, adicione o nome do método de teste::

    $ ./manage.py test animals.AnimalTestCase.testFluffyAnimals
    
.. versionadded:: 1.2
   The ability to select individual doctests was added.

You can use the same rules if you're using doctests. Django will use the
test label as a path to the test method or class that you want to run.
If your ``models.py`` or ``tests.py`` has a function with a doctest, or
class with a class-level doctest, you can invoke that test by appending the
name of the test method or class to the label::

    $ ./manage.py test animals.classify

If you want to run the doctest for a specific method in a class, add the
name of the method to the label::

    $ ./manage.py test animals.Classifier.run

If you're using a ``__test__`` dictionary to specify doctests for a
module, Django will use the label as a key in the ``__test__`` dictionary
for defined in ``models.py`` and ``tests.py``.

.. versionadded:: 1.2
   You can now trigger a graceful exit from a test run by pressing ``Ctrl-C``.

If you press ``Ctrl-C`` while the tests are running, the test runner will
wait for the currently running test to complete and then exit gracefully.
During a graceful exit the test runner will output details of any test
failures, report on how many tests were run and how many errors and failures
were encountered, and destroy any test databases as usual. Thus pressing
``Ctrl-C`` can be very useful if you forget to pass the :djadminopt:`--failfast`
option, notice that some tests are unexpectedly failing, and want to get details
on the failures without waiting for the full test run to complete.

If you do not want to wait for the currently running test to finish, you
can press ``Ctrl-C`` a second time and the test run will halt immediately,
but not gracefully. No details of the tests run before the interruption will
be reported, and any test databases created by the run will not be destroyed.

.. admonition:: Test with warnings enabled

    It's a good idea to run your tests with Python warnings enabled:
    ``python -Wall manage.py test``. The ``-Wall`` flag tells Python to
    display deprecation warnings. Django, like many other Python libraries,
    uses these warnings to flag when features are going away. It also might
    flag areas in your code that aren't strictly wrong but could benefit
    from a better implementation.
    
Running tests outside the test runner
-------------------------------------

If you want to run tests outside of ``./manage.py test`` -- for example,
from a shell prompt -- you will need to set up the test
environment first. Django provides a convenience method to do this::

    >>> from django.test.utils import setup_test_environment
    >>> setup_test_environment()

This convenience method sets up the test database, and puts other
Django features into modes that allow for repeatable testing.

The call to :meth:`~django.test.utils.setup_test_environment` is made
automatically as part of the setup of `./manage.py test`. You only
need to manually invoke this method if you're not using running your
tests via Django's test runner.

O banco de dados de teste
-------------------------

Testes que necessitam de uma base de dados (nomeadamente, testes de modelo) não
usarão seu banco de dados "real" (produção). Um banco de dados vazio é criado
em separado para os testes.

Independentemente de os testes passarem ou falharem, o banco de dados de teste
é destruído quando todos os testes forem executados.

Por padrão, o nome deste banco de dados de teste é o valor da configuração
:setting:`DATABASE_NAME` adicionando o prefixo ``test_``. Quando um banco de
dados SQLite é utilizado, os testes usarão bancos de dados na memória (ou seja,
todo o banco será criado somente na memória, não utilizando nada do sistema de
arquivos). Se você quiser usar um nome diferente para o banco de dados de teste,
especifique o parâmetro de configuração :setting:`TEST_DATABASE_NAME`.

Além de utilizar um banco de dados separado, o executor de testes usará os
mesmos parâmetros de banco de dados do seu arquivo de configuração:
:setting:`DATABASE_ENGINE`, :setting:`DATABASE_USER`, :setting:`DATABASE_HOST`,
etc. O banco de dados de teste é criado pelo usuário especificado em
:setting:`DATABASE_USER`, então é necessário garantir que esta conta de usuário
tem privilégios suficientes para criar um novo banco de dados no sistema.

Para um controle apurado sobre a codificação de caractere de seu banco de dados
de teste, use o parâmetro de configuração :setting:`TEST_DATABASE_CHARSET`. Se
você está utilizando MySQL, você pode também usar o parâmetro
:setting:`TEST_DATABASE_COLLATION` para controlar uma collation particular
utilizada pelo banco de dados de teste. Veja a
:doc:`documentação de configurações </ref/settings>` para mais detalhes dessas
configurações avançadas.

.. _topics-testing-masterslave:

Testing master/slave configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.2

If you're testing a multiple database configuration with master/slave
replication, this strategy of creating test databases poses a problem.
When the test databases are created, there won't be any replication,
and as a result, data created on the master won't be seen on the
slave.

To compensate for this, Django allows you to define that a database is
a *test mirror*. Consider the following (simplified) example database
configuration::

    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.mysql',
            'NAME': 'myproject',
            'HOST': 'dbmaster',
             # ... plus some other settings
        },
        'slave': {
            'ENGINE': 'django.db.backends.mysql',
            'NAME': 'myproject',
            'HOST': 'dbslave',
            'TEST_MIRROR': 'default'
            # ... plus some other settings
        }
    }

In this setup, we have two database servers: ``dbmaster``, described
by the database alias ``default``, and ``dbslave`` described by the
alias ``slave``. As you might expect, ``dbslave`` has been configured
by the database administrator as a read slave of ``dbmaster``, so in
normal activity, any write to ``default`` will appear on ``slave``.

If Django created two independent test databases, this would break any
tests that expected replication to occur. However, the ``slave``
database has been configured as a test mirror (using the
:setting:`TEST_MIRROR` setting), indicating that under testing,
``slave`` should be treated as a mirror of ``default``.

When the test environment is configured, a test version of ``slave``
will *not* be created. Instead the connection to ``slave``
will be redirected to point at ``default``. As a result, writes to
``default`` will appear on ``slave`` -- but because they are actually
the same database, not because there is data replication between the
two databases.

.. _topics-testing-creation-dependencies:

Controlling creation order for test databases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.3

By default, Django will always create the ``default`` database first.
However, no guarantees are made on the creation order of any other
databases in your test setup.

If your database configuration requires a specific creation order, you
can specify the dependencies that exist using the
:setting:`TEST_DEPENDENCIES` setting. Consider the following
(simplified) example database configuration::

    DATABASES = {
        'default': {
             # ... db settings
             'TEST_DEPENDENCIES': ['diamonds']
        },
        'diamonds': {
            # ... db settings
        },
        'clubs': {
            # ... db settings
            'TEST_DEPENDENCIES': ['diamonds']
        },
        'spades': {
            # ... db settings
            'TEST_DEPENDENCIES': ['diamonds','hearts']
        },
        'hearts': {
            # ... db settings
            'TEST_DEPENDENCIES': ['diamonds','clubs']
        }
    }

Under this configuration, the ``diamonds`` database will be created first,
as it is the only database alias without dependencies. The ``default`` and
``clubs`` alias will be created next (although the order of creation of this
pair is not guaranteed); then ``hearts``; and finally ``spades``.

If there are any circular dependencies in the
:setting:`TEST_DEPENDENCIES` definition, an ``ImproperlyConfigured``
exception will be raised.

Outras condições de testes
--------------------------

Independentemente do valor do :setting:`DEBUG` do seu arquivo de configuração,
todos os testes do Django rodam com :setting:`DEBUG=False`. Isto é para
assegurar que a saída observada de seu código seja igual ao da aplicação em
produção.

Entendendo a saída do teste
---------------------------

Quando roda seus testes, você visualiza um número de mensagens à medida que o
executor de testes se prepara. Você pode controlar o nível de detalhe dessas
mensagens com a opção de linha de comando ``verbosity``::

    Creating test database...
    Creating table myapp_animal
    Creating table myapp_mineral
    Loading 'initial_data' fixtures...
    No fixtures found.

Isso informa que o executor de testes está criando um banco de teste, como
descrito na seção anterior.

Uma vez que o banco de testes foi criado, o Django rodará os seus testes.
Se tudo correr bem, você verá algo do tipo::


    ----------------------------------------------------------------------
    Ran 22 tests in 0.221s

    OK

Se existirem falhas, entretanto, você verá os detalhes completos sobre quais
testes falharam::

    ======================================================================
    FAIL: Doctest: ellington.core.throttle.models
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "/dev/django/test/doctest.py", line 2153, in runTest
        raise self.failureException(self.format_failure(new.getvalue()))
    AssertionError: Failed doctest test for myapp.models
      File "/dev/myapp/models.py", line 0, in models

    ----------------------------------------------------------------------
    File "/dev/myapp/models.py", line 14, in myapp.models
    Failed example:
        throttle.check("actor A", "action one", limit=2, hours=1)
    Expected:
        True
    Got:
        False

    ----------------------------------------------------------------------
    Ran 2 tests in 0.048s

    FAILED (failures=1)


Uma explicação completa sobre essa saída de erro está fora do escopo deste
documento, mas ela é bem intuitiva. Você pode consultar a documentação da
biblioteca ``unittest`` do Python para maiores detalhes.

Note que o código retornado pelo script executor de testes é o número total de
testes que falharam. Se todos os testes passarem, o código de retorno é 0. Este
recurso é útil se você está usando script executor de testes em um script shell
e precisa verificar o sucesso ou falha naquele nível.

Ferramentas de teste
====================

O Django provê um pequeno conjunto de ferramentas que são uma verdadeira mão-
na-roda na hora de escrever os testes.

.. _test-client:

O cliente de teste
------------------

.. module:: django.test.client
   :synopsis: Django's test client.

O cliente de teste é uma classe Python que age como um navegador Web,
permitindo a você testar suas views e interagir com suas aplicações feitas em
Django programaticamente.

Algumas das coisas que você pode fazer com o cliente de teste são:

    * Simular requisições GET e POST em uma URL e observar a resposta --
      tudo desde o nível baixo do HTTP (os cabeçalhos de resultado e códigos de
      status) até o conteúdo da página.

    * Testar se a view correta é executada para uma dada URL.

    * Testar que uma dada requisição é gerada por um determinado template,
      com um determinado contexto de template que contém certos valores.

Note que este cliente de teste não tem o propósito de ser um substituto para
Twill_, Selenium_, ou outros frameworks "in-browser". O cliente de teste do
Django tem um foco diferente. Em resumo:

    * Use o cliente de teste do Django para atestar que a view correta está
      sendo chamada e que a view está recebendo os dados de contexto corretos.

    * Use frameworks in-browser como Twill e Selenium para testar HTML gerados
      e *comportamento* de páginas Web, ou seja, funcionalidade JavaScript.

Uma test suite completa deve usar uma combinação de ambos tipos de testes.

.. _Twill: http://twill.idyll.org/
.. _Selenium: http://www.openqa.org/selenium/

Visão geral e um exemplo rápido
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Para usar o cliente de teste, instancie ``django.test.client.Client`` e acesse
páginas Web::

    >>> from django.test.client import Client
    >>> c = Client()
    >>> response = c.post('/login/', {'username': 'john', 'password': 'smith'})
    >>> response.status_code
    200
    >>> response = c.get('/customer/details/')
    >>> response.content
    '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 ...'

Como esse exemplo sugere, você pode instanciar ``Client`` de dentro de uma
sessão do interpretador interativo do Python.

Note algumas coisas importantes sobre como o cliente de teste funciona:

    * O cliente de teste *não* requer que o servidor Web esteja rodando. Aliás,
      ele rodará muito bem sem nenhum servidor Web! Isso se deve ao fato de que
      ele evita o esforço extra do HTTP e lida diretamente com o framework
      Django. Isso faz com que os testes unitários rodem bem mais rápido.

    * Ao acessar as páginas, lembre-se de especificar o *caminho* da URL, e não
      todo o domínio. Por exemplo, isto é correto::

          >>> c.get('/login/')

      E isto incorreto::

          >>> c.get('http://www.example.com/login/')

      O cliente de testes não é capaz de acessar páginas Web que não fazem parte
      do seu projeto Django. Se você precisa acessar outras páginas Web, utilize
      algum módulo da biblioteca padrão do Python como urllib_ ou urllib2_.

    * Para resolver URLs, o cliente de testes usa o URLconf que está
      especificado no parâmetro de configuração :setting:`ROOT_URLCONF`.

    * Apesar de o exemplo acima funcionar no interpretador interativo do
      Python, algumas funcionalidades do cliente de teste, notadamente as
      relacionadas a templates, somente estão disponíveis *enquanto os testes
      estão sendo rodados*.

      O motivo disso é porque o executor de testes do Django faz um pouco de
      magia negra para determinar qual template foi carregado por uma
      determinada view. Essa magia negra (essencialmente um patch no sistema
      de templates na memória) acontece somente durante a execução dos testes.

    * By default, the test client will disable any CSRF checks
      performed by your site.

      .. versionadded:: 1.2.2

      If, for some reason, you *want* the test client to perform CSRF
      checks, you can create an instance of the test client that
      enforces CSRF checks. To do this, pass in the
      ``enforce_csrf_checks`` argument when you construct your
      client::

          >>> from django.test import Client
          >>> csrf_client = Client(enforce_csrf_checks=True)

.. _urllib: http://docs.python.org/lib/module-urllib.html
.. _urllib2: http://docs.python.org/lib/module-urllib2.html

Fazendo requisições
~~~~~~~~~~~~~~~~~~~

Use a classe ``django.test.client.Client`` para fazer as requisições. Ela não
requer argumentos em sua contrução:

.. class:: Client()

    Uma vez que você tenha uma instância de ``Client``, você pode chamar
    qualquer um dos seguintes métodos:

    .. method:: Client.get(path, data={}, **extra)

        Faz uma requisição GET no ``path`` informado e devolve um objeto
        ``Response``, que está documentado abaixo.

        Os pares de chave-valor no dicionário ``data`` são usados para criar os
        dados que serão enviados via GET. Por exemplo::

            >>> c = Client()
            >>> c.get('/customers/details/', {'name': 'fred', 'age': 7})

        ...resultará em uma requisição GET equivalente a::

            /customers/details/?name=fred&age=7

        The ``extra`` keyword arguments parameter can be used to specify
        headers to be sent in the request. For example::

            >>> c = Client()
            >>> c.get('/customers/details/', {'name': 'fred', 'age': 7},
            ...       HTTP_X_REQUESTED_WITH='XMLHttpRequest')

        ...will send the HTTP header ``HTTP_X_REQUESTED_WITH`` to the
        details	view, which is a good way to test code paths that use the
        :meth:`django.http.HttpRequest.is_ajax()` method.
        
        .. admonition:: CGI specification

            The headers sent via ``**extra`` should follow CGI_ specification.
            For example, emulating a different "Host" header as sent in the
            HTTP request from the browser to the server should be passed
            as ``HTTP_HOST``. 

            .. _CGI: http://www.w3.org/CGI/

        If you already have the GET arguments in URL-encoded form, you can
        use that encoding instead of using the data argument. For example,
        the previous GET request could also be posed as::

        >>> c = Client()
        >>> c.get('/customers/details/?name=fred&age=7')

        If you provide a URL with both an encoded GET data and a data argument,
        the data argument will take precedence.

        If you set ``follow`` to ``True`` the client will follow any redirects
        and a ``redirect_chain`` attribute will be set in the response object
        containing tuples of the intermediate urls and status codes.

        If you had an url ``/redirect_me/`` that redirected to ``/next/``, that
        redirected to ``/final/``, this is what you'd see::

            >>> response = c.get('/redirect_me/', follow=True)
            >>> response.redirect_chain
            [(u'http://testserver/next/', 302), (u'http://testserver/final/', 302)]

    .. method:: Client.post(path, data={}, content_type=MULTIPART_CONTENT, **extra)

        Faz uma requisição POST no ``path`` informado e devolve um objeto
        ``Response``, que está documentado abaixo.

        Os pares de chave-valor no dicionário ``data`` são usados para enviar os
        dados via POST. Por exemplo::

            >>> c = Client()
            >>> c.post('/login/', {'name': 'fred', 'passwd': 'secret'})

        ...resultará em uma requisição POST a esta URL::

            /login/

        ...com estes dados de POST::

            name=fred&passwd=secret

        Se você informa o ``content_type`` (ex: ``text/xml`` para um XML), o
        conteúdo de ``data`` será enviado como está na requisição POST,
        utilizando ``content_type`` no cabeçalho HTTP ``Content-Type``.

        Se você não informa um valor para ``content_type``, os valores em
        ``data`` serão transmitidos como um tipo de conteúdo
        ``multipart/form-data``. Nesse caso, os pares chave-valor em ``data``
        serão codificados como uma mensagem multipart e usados para criar os
        dados de POST.

        Para enviar múltiplos valores para uma chave -- por exemplo, para
        especificar as seleções para um ``<select multiple>`` -- informe os
        valores como uma lista ou tupla para a chave. Por exemplo, este valor de
        ``data`` enviará três valores selecionados para o campo de nome
        ``choices``::

            {'choices': ('a', 'b', 'd')}

        Enviar arquivos é um caso especial. Para postar um arquivo, você só
        precisa informar o nome do campo como chave, e um manipulador de arquivo
        apontando para o arquivo que deseja postar como valor. Por exemplo::

            >>> c = Client()
            >>> f = open('wishlist.doc')
            >>> c.post('/customers/wishes/', {'name': 'fred', 'attachment': f})
            >>> f.close()

        (O nome ``attachment`` aqui não é relevante; use qualquer nome que o seu
        código de processamento de arquivo espera.)

        Perceba que você deve fechar o arquivo manualmente depois que ele foi
        informado para o ``post()``.

        The ``extra`` argument acts the same as for :meth:`Client.get`.
        
        If the URL you request with a POST contains encoded parameters, these
        parameters will be made available in the request.GET data. For example,
        if you were to make the request::

        >>> c.post('/login/?visitor=true', {'name': 'fred', 'passwd': 'secret'})

        ... the view handling this request could interrogate request.POST
        to retrieve the username and password, and could interrogate request.GET
        to determine if the user was a visitor.

        If you set ``follow`` to ``True`` the client will follow any redirects
        and a ``redirect_chain`` attribute will be set in the response object
        containing tuples of the intermediate urls and status codes.

    .. method:: Client.head(path, data={}, follow=False, **extra)

        Makes a HEAD request on the provided ``path`` and returns a ``Response``
        object. Useful for testing RESTful interfaces. Acts just like
        :meth:`Client.get` except it does not return a message body.

        If you set ``follow`` to ``True`` the client will follow any redirects
        and a ``redirect_chain`` attribute will be set in the response object
        containing tuples of the intermediate urls and status codes.

    .. method:: Client.options(path, data={}, follow=False, **extra)

        Makes an OPTIONS request on the provided ``path`` and returns a
        ``Response`` object. Useful for testing RESTful interfaces.

        If you set ``follow`` to ``True`` the client will follow any redirects
        and a ``redirect_chain`` attribute will be set in the response object
        containing tuples of the intermediate urls and status codes.

        The ``extra`` argument acts the same as for :meth:`Client.get`.

    .. method:: Client.put(path, data={}, content_type=MULTIPART_CONTENT, follow=False, **extra)

        Makes a PUT request on the provided ``path`` and returns a
        ``Response`` object. Useful for testing RESTful interfaces. Acts just
        like :meth:`Client.post` except with the PUT request method.

        If you set ``follow`` to ``True`` the client will follow any redirects
        and a ``redirect_chain`` attribute will be set in the response object
        containing tuples of the intermediate urls and status codes.

    .. method:: Client.delete(path, follow=False, **extra)

        Makes an DELETE request on the provided ``path`` and returns a
        ``Response`` object. Useful for testing RESTful interfaces.

        If you set ``follow`` to ``True`` the client will follow any redirects
        and a ``redirect_chain`` attribute will be set in the response object
        containing tuples of the intermediate urls and status codes.

        The ``extra`` argument acts the same as for :meth:`Client.get`.

    .. method:: Client.login(**credentials)

        Se seu site Django usa o :doc:`sistema de autenticação </topics/auth>` e
        você precisa logar usuários, você pode usar o método ``login()`` do
        cliente de testes para simular o efeito de um usuário logando no site.

        Depois de chamar este método, o cliente de testes terá todos os cookies
        e dados de sessão necessários para passar a qualquer teste baseado em
        login que faça parte de uma view.

        O formato do argumento ``credentials`` depende de qual :ref:`backend de
        autenticação <authentication-backends>` você está usando (que é
        configurado pelo parâmetro de configuração
        :setting:`AUTHENTICATION_BACKENDS`). Se você está usando o backend
        padrão de autenticação do Django (``ModelBackend``), ``credentials``
        deve ser o nome do usuário e a senha, informados como argumentos
        nomeados::

            >>> c = Client()
            >>> c.login(username='fred', password='secret')
            >>> # Agora você pode acessar a view que somente está disponível
            >>> # para usuários logados.

        Se você está usando um backend de autenticação diferente, este método
        requer credenciais diferentes. Ele requer as mesmas credenciais que o
        método ``authenticate()`` do backend.

        ``login()`` devolve ``True`` se as credenciais foram aceitas e o login
        ocorreu com sucesso.

        Finalmente, você precisa lembrar-se de criar contas de usuários antes de
        utilizar este método. Como explicado acima, o executor de testes utiliza
        uma base de dados de teste, que não contém usuários criados. Como
        resultado, contas que são válidas no seu site em produção não
        funcionarão nas condições de teste. Você precisa criar os usuários como
        parte de sua test suite -- tanto manualmente (utilizando a API de
        modelos do Django) ou com uma test fixture.

        Lembre-se que se você quiser que seu usuários de teste tenha uma senha,
        você não pode setar a senha do usuário usando o atributo password
        diretamente -- você deve usar a função
        :meth:`~django.contrib.auth.models.User.set_password()` para armazenar
        corretamente uma senha criptografada. Alternativamente, você pode usar o
        método helper
        :meth:`~django.contrib.auth.models.UserManager.create_user` para criar
        um novo usuário com a senha criptografada corretamente.

    .. method:: Client.logout()

        Se o seu site usa o :doc:`sistema de autenticação </topics/auth>` do
        Django, o método ``logout()`` pode ser utilizado para simular o efeito
        de um usuário se deslogar do seu site.

        Depois de chamar este método, o cliente de teste terá todos os cookies e
        dados de sessão retornados para os valores padrões. Requisições
        subseqüentes parecerão vir de um usuário anônimo AnonymousUser.

Testando as respostas
~~~~~~~~~~~~~~~~~~~~~

Ambos os métodos ``get()`` e ``post()`` devolvem um objeto ``Response``. Este
objeto ``Response`` *não* é o mesmo que o objeto ``HttpResponse`` retornado
pelas views do Django; o objeto de resposta do teste tem dados adicionais
úteis para serem verificados pelo código de teste.

Especificamente, o objeto ``Response`` tem os seguintes atributos:

.. class:: Response()

    .. attribute:: client

        O cliente de teste que foi usado para fazer a requisição que resultou na
        resposta.

    .. attribute:: content

        O corpo da resposta, como uma string. Este é o conteúdo final da página
        que foi gerada pela view, ou alguma mensagem de erro.

    .. attribute:: context

        A instância ``Context`` que foi utilizada pelo template para produzir o
        conteúdo da resposta.

        Se a página gerada utilizou múltiplos templates, então o ``context``
        será uma lista de objetos ``Context``, na ordem em que foram utilizados.

    .. attribute:: request

        Os dados da requisição que provocaram a resposta.

    .. attribute:: status_code

        O status da resposta HTTP, como um inteiro. Veja RFC2616_ para uma lista
        completa de códigos de status HTTP.

    .. attribute:: template

        A instância de ``Template`` que foi utilizada para gerar o conteúdo
        final. Use ``template.name`` para obter o nome do arquivo do template,
        se o template foi carregado de um arquivo. (O nome é uma string como
        ``'admin/index.html'``.)

        Se a página gerada utilizou vários templates -- ex: utilizando
        :ref:`herança de templates <template-inheritance>` -- então ``template``
        será uma lista de instâncias de ``Template``, na ordem em que eles foram
        utilizados.

Você pode também usar uma sintaxe de dicionário no objeto de resposta para
obter o valor de qualquer configuração nos cabeçalhos HTTP. Por exemplo, você
pode determinar o conteúdo de uma resposta usando ``response['Content-Type']``.

.. _RFC2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Exceções
~~~~~~~~

Se você aponta o cliente de testes para uma view que lança uma exceção, esta
exceção estará visível no test case. Você pode então usar blocos ``try...catch``
ou ``unittest.TestCase.assertRaises()`` para testar por exceções.

As únicas exceções que não estão visíveis ao cliente de teste são ``Http404``,
``PermissionDenied`` e ``SystemExit``. O Django captura estas exceções
internamente e converte-as em códigos de resposta HTTP adequados. Nesses casos,
você pode verificar ``response.status_code`` no seu código.


Estado persistente (persistent state)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

O cliente de teste é "stateful", ou seja, mantém o estado. Se uma resposta
retorna um cookie, então esse cookie será armazenado no cliente de teste e
enviado com todas as requisições subseqüentes de ``get()`` e ``post()``.

Políticas de expiração desses cookies não são seguidas. Se você quiser que um
cookie expire, delete-o manualmente ou crie uma nova instância de ``Client``
(o que irá deletar todos os cookies).

Um cliente de teste possui dois atributos que armazenam informações de estado
persistente. Você pode acessar essas propriedades como parte de uma condição
de teste.

.. attribute:: Client.cookies

    Um objeto ``SimpleCookie`` Python, contendo os valores atuais de todos os
    cookies do cliente. Veja a `Documentação do módulo cookie`_ para saber mais.

.. attribute:: Client.session

    A dictionary-like object containing session information. See the
    :doc:`session documentation</topics/http/sessions>` for full details.
    
    To modify the session and then save it, it must be stored in a variable
    first (because a new ``SessionStore`` is created every time this property
    is accessed)::

        def test_something(self):
            session = self.client.session
            session['somekey'] = 'test'
            session.save()

.. _Documentação do módulo cookie: http://docs.python.org/lib/module-Cookie.html

Exemplo
~~~~~~~

Segue um teste unitário simples usando o cliente de teste::

    import unittest
    from django.test.client import Client

    class SimpleTest(unittest.TestCase):
        def setUp(self):
            # Cada teste precisa de um cliente.
            self.client = Client()

        def test_details(self):
            # Faz uma requisição GET.
            response = self.client.get('/customer/details/')

            # Verifica se a resposta foi 200 OK.
            self.failUnlessEqual(response.status_code, 200)

            # Verifica se o contexto utilizado contém 5 customers.
            self.failUnlessEqual(len(response.context['customers']), 5)

The request factory
-------------------

.. Class:: RequestFactory

.. versionadded:: 1.3

The :class:`~django.test.client.RequestFactory` shares the same API as
the test client. However, instead of behaving like a browser, the
RequestFactory provides a way to generate a request instance that can
be used as the first argument to any view. This means you can test a
view function the same way as you would test any other function -- as
a black box, with exactly known inputs, testing for specific outputs.

The API for the :class:`~django.test.client.RequestFactory` is a slightly
restricted subset of the test client API:

    * It only has access to the HTTP methods :meth:`~Client.get()`,
      :meth:`~Client.post()`, :meth:`~Client.put()`,
      :meth:`~Client.delete()`, :meth:`~Client.head()` and
      :meth:`~Client.options()`.

    * These methods accept all the same arguments *except* for
      ``follows``. Since this is just a factory for producing
      requests, it's up to you to handle the response.

    * It does not support middleware. Session and authentication
      attributes must be supplied by the test itself if required
      for the view to function properly.

Example
~~~~~~~

The following is a simple unit test using the request factory::

    from django.utils import unittest
    from django.test.client import RequestFactory

    class SimpleTest(unittest.TestCase):
        def setUp(self):
            # Every test needs access to the request factory.
            self.factory = RequestFactory()

        def test_details(self):
            # Create an instance of a GET request.
            request = self.factory.get('/customer/details')

            # Test my_view() as if it were deployed at /customer/details
            response = my_view(request)
            self.assertEqual(response.status_code, 200)

TestCase
--------

.. currentmodule:: django.test

Uma classe de teste unitário normal do Python extende uma classe base
``unittest.TestCase``. O Djagno provê uma extensão desta classe:

.. class:: TestCase()

Esta classe provê algumas capacidades adicionais qeu podem ser úteis para testar
site Web.

Converter um ``unittest.TestCase`` normal para um Django ``TestCase`` é fácil:
basta mudar a classe base de seu teste de ``unittest.TestCase`` para
``django.test.TestCase``. Todas as funcionalidades padrões de teste unitário do
Python continuarão disponíveis, mas serão aumentadas com algumas adições úteis, incluindo:

    * Automatic loading of fixtures.

    * Wraps each test in a transaction.

    * Creates a TestClient instance.

    * Django-specific assertions for testing for things
      like redirection and form errors.

.. class:: TransactionTestCase()

Django ``TestCase`` classes make use of database transaction facilities, if
available, to speed up the process of resetting the database to a known state
at the beginning of each test. A consequence of this, however, is that the
effects of transaction commit and rollback cannot be tested by a Django
``TestCase`` class. If your test requires testing of such transactional
behavior, you should use a Django ``TransactionTestCase``.

``TransactionTestCase`` and ``TestCase`` are identical except for the manner
in which the database is reset to a known state and the ability for test code
to test the effects of commit and rollback. A ``TransactionTestCase`` resets
the database before the test runs by truncating all tables and reloading
initial data. A ``TransactionTestCase`` may call commit and rollback and
observe the effects of these calls on the database.

A ``TestCase``, on the other hand, does not truncate tables and reload initial
data at the beginning of a test. Instead, it encloses the test code in a
database transaction that is rolled back at the end of the test.  It also
prevents the code under test from issuing any commit or rollback operations
on the database, to ensure that the rollback at the end of the test restores
the database to its initial state. In order to guarantee that all ``TestCase``
code starts with a clean database, the Django test runner runs all ``TestCase``
tests first, before any other tests (e.g. doctests) that may alter the
database without restoring it to its original state.

When running on a database that does not support rollback (e.g. MySQL with the
MyISAM storage engine), ``TestCase`` falls back to initializing the database
by truncating tables and reloading initial data.


.. note::
    The ``TestCase`` use of rollback to un-do the effects of the test code
    may reveal previously-undetected errors in test code.  For example,
    test code that assumes primary keys values will be assigned starting at
    one may find that assumption no longer holds true when rollbacks instead
    of table truncation are being used to reset the database.  Similarly,
    the reordering of tests so that all ``TestCase`` classes run first may
    reveal unexpected dependencies on test case ordering.  In such cases a
    quick fix is to switch the ``TestCase`` to a ``TransactionTestCase``.
    A better long-term fix, that allows the test to take advantage of the
    speed benefit of ``TestCase``, is to fix the underlying test problem.

O cliente de teste default
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. attribute:: TestCase.client

Cada teste em uma instância de ``django.test.TestCase`` tem acesso a uma
instância do cliente de testes do Django. Esse cliente pode ser acessado como
``self.client``. O cliente é recriado para cada teste, então você não tem de
se preocupar sobre o estado (como os cookies) ser levado de um teste a outro.

Isso significa que, em vez de instanciar um ``Client`` em cada teste::

    import unittest
    from django.test.client import Client

    class SimpleTest(unittest.TestCase):
        def test_details(self):
            client = Client()
            response = client.get('/customer/details/')
            self.failUnlessEqual(response.status_code, 200)

        def test_index(self):
            client = Client()
            response = client.get('/customer/index/')
            self.failUnlessEqual(response.status_code, 200)

...você só precisa se referir a ``self.client``, como::

    from django.test import TestCase

    class SimpleTest(TestCase):
        def test_details(self):
            response = self.client.get('/customer/details/')
            self.failUnlessEqual(response.status_code, 200)

        def test_index(self):
            response = self.client.get('/customer/index/')
            self.failUnlessEqual(response.status_code, 200)

Customizing the test client
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.3

.. attribute:: TestCase.client_class

If you want to use a different ``Client`` class (for example, a subclass
with customized behavior), use the :attr:`~TestCase.client_class` class
attribute::

    from django.test import TestCase
    from django.test.client import Client

    class MyTestClient(Client):
        # Specialized methods for your environment...

    class MyTest(TestCase):
        client_class = MyTestClient

        def test_my_stuff(self):
            # Here self.client is an instance of MyTestClient...

.. _topics-testing-fixtures:

Carga de fixture
~~~~~~~~~~~~~~~~

.. attribute:: TestCase.fixtures

Um teste para um site Web com banco de dados não tem muita utilidade se não
existir dados no banco. Para facilitar a carga destes dados no banco, a classe
``TestCase`` do Django proporciona uma maneira de carregar **fixtures**.

Uma fixture é uma coleção de dados que o Django sabe como importar para um
banco de dados. Por exemplo, se o seu site tem contas de usuários, você pode
configurar uma fixture de usuários no intuito de popular seu banco durante
os testes.

O método mais simples e direto de criar uma fixture é usar o comando
``manage.py dumpdata``. Isso assume que você já tem algum dado em seu banco.
Veja a :djadmin:`documentação do dumpdata <dumpdata>` para mais detalhes.

.. note::
    Se você já rodou alguma vez o ``manage.py syncdb``, você já usou fixture
    sem nem mesmo saber! Quando você dá um ``syncdb`` no banco de dados pela
    primeira vez, o Django instala uma fixture chamada ``initial_data``.
    Isso dá a possibilidade de popular um banco de dados novo com qualquer dado
    relacional, como um conjunto padrão de categorias, por exemplo.

    Fixtures com outros nomes podem sempre ser instaladas manualmente usando
    o comando ``manage.py loaddata``.

Uma vez que você criou uma fixture e colocou em algum lugar em seu projeto
Django, você pode utilizá-la nos seus testes unitários especificando um
atributo de classe ``fixtures`` na sua subclasse de ``django.test.TestCase``::


    from django.test import TestCase
    from myapp.models import Animal

    class AnimalTestCase(TestCase):
        fixtures = ['mammals.json', 'birds']

        def setUp(self):
            # Definições de testes como anteriormente.

        def testFluffyAnimals(self):
            # Um teste que usa fixtures.

Eis o que acontecerá nesse caso:

    * No início de cada test case, antes de ``setUp()`` ser rodado, o Django
      limpará o banco de dados, retornando um banco de dados no estado que
      estava diretamente após a chamada de ``syncdb``.

    * Em seguida, todas as fixtures nomeadas são instaladas. Nesse exemplo, o
      Django instalará qualquer fixture JSON chamada ``mammals``, seguida por
      qualquer fixture chamada ``birds``. Veja a :djadmin:`documentação do
      loaddata` para mais detalhes sobre a definição e a instalação de fixtures.

Esse procedimento de limpeza/carga é repetido para cada teste no test case,
então você pode ter certeza de que o resultado de um teste não será afetado por
outro teste, ou pela ordem de execução dos testes.

Configuração do URLconf
~~~~~~~~~~~~~~~~~~~~~~~

.. attribute:: TestCase.urls

Se a sua aplicação possui views, você pode querer incluir testes que utilizam
o cliente de testes para exercitá-las. Entretanto, um usuário final é livre
para configurar as views em sua aplicação em qualquer URL de sua preferência.
Isso significa que seus testes não podem contar com o fato de que suas views
estarão disponíveis em uma URL em particular.

A fim de proporcionar URLs confiáveis para seu teste, ``django.test.TestCase``
tem a capacidade de customizar a configuração do URLconf pelo período de
execução dos testes. Se sua instância de ``TestCase`` define o atributo
``urls``, o ``TestCase`` usará os valores deste atributo como o
``ROOT_URLCONF`` pelo período de execução do teste.

Por exemplo::

    from django.test import TestCase

    class TestMyViews(TestCase):
        urls = 'myapp.test_urls'

        def testIndexPageView(self):
            # Aqui você testará sua view usando ``Client``.

Esse test case utilizará o conteúdo de ``myapp.test_urls`` como o URLconf
durante a execução do teste.

.. _emptying-test-outbox:

Multi-database support
~~~~~~~~~~~~~~~~~~~~~~

.. attribute:: TestCase.multi_db

.. versionadded:: 1.2

Django sets up a test database corresponding to every database that is
defined in the :setting:`DATABASES` definition in your settings
file. However, a big part of the time taken to run a Django TestCase
is consumed by the call to ``flush`` that ensures that you have a
clean database at the start of each test run. If you have multiple
databases, multiple flushes are required (one for each database),
which can be a time consuming activity -- especially if your tests
don't need to test multi-database activity.

As an optimization, Django only flushes the ``default`` database at
the start of each test run. If your setup contains multiple databases,
and you have a test that requires every database to be clean, you can
use the ``multi_db`` attribute on the test suite to request a full
flush.

For example::

    class TestMyViews(TestCase):
        multi_db = True

        def testIndexPageView(self):
            call_some_test_code()

This test case will flush *all* the test databases before running
``testIndexPageView``.

Esvaziando a caixa de saída de teste
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Se você usa a classe Django ``TestCase``, o executor de testes limpará o
conteúdo da caixa de saída de e-mail no início de cada teste.

Para mais detalhes sobre os serviços de e-mail durante os teste, veja
`Serviços de e-mail`_.

Assertions
~~~~~~~~~~

.. versionchanged:: 1.2
    Addded ``msg_prefix`` argument.

Como numa classe Python ``unittest.TestCase`` normal que implementa métodos de
asserção como ``assertTrue`` e ``assertEquals``, a classe customizada
``TestCase`` do Django disponibiliza alguns métodos de asserção customizados
que são úteis para testar aplicações Web:

The failure messages given by the assertion methods can be customized
with the ``msg_prefix`` argument. This string will be prefixed to any
failure message generated by the assertion. This allows you to provide
additional details that may help you to identify the location and
cause of an failure in your test suite.

.. method:: TestCase.assertContains(response, text, count=None, status_code=200)

    Testa se uma instância de ``Response`` produziu o ``status_code`` informado
    e que o ``text`` aparece no conteúdo da resposta. Se ``count`` é fornecido,
    ``text`` deve ocorrer exatamente ``count`` vezes na resposta.

.. method:: TestCase.assertNotContains(response, text, status_code=200)

    Testa se uma instância de ``Response`` produziu o ``status_code`` informado
    e que o ``text`` não aparece no conteúdo da resposta.

.. method:: TestCase.assertFormError(response, form, field, errors)

    Testa se um campo no formulário lança a lista de erros fornecida quando
    gerado no formulário.

    ``form`` é o nome da instância de ``Form`` informada ao contexto do
    template.

    ``field`` é o nome do campo no formulário para verificar. Se ``field``
    tem um valor de ``None``, erros não relacionados a campos (erros que você
    pode acessar via ``form.non_field_errors()``) serão verificados.

    ``errors`` é uma string de erro, ou uma lista de strings de erro, que
    são esperados como resultado da validação do formulário.

.. method:: TestCase.assertTemplateUsed(response, template_name)
    Testa se o template com o nome informado foi usado na geração da resposta.

    O nome é uma string como ``'admin/index.html'``.

.. method:: TestCase.assertTemplateNotUsed(response, template_name)

    Testa se o template com o nome informado *não* foi usado na geração da
    resposta.

.. method:: TestCase.assertRedirects(response, expected_url, status_code=302, target_status_code=200)

    Teste se a resposta devolve um status de redirecionamento ``status_code``,
    se redirecionou para a URL ``expected_url``  (incluindo quaisquer dados
    GET), e a página subseqüente foi recebida com o ``target_status_code``.

    If your request used the ``follow`` argument, the ``expected_url`` and
    ``target_status_code`` will be the url and status code for the final
    point of the redirect chain.
    
.. method:: TestCase.assertQuerysetEqual(qs, values, transform=repr)

    .. versionadded:: 1.3

    Asserts that a queryset ``qs`` returns a particular list of values ``values``.

    The comparison of the contents of ``qs`` and ``values`` is performed using
    the function ``transform``; by default, this means that the ``repr()`` of
    each value is compared. Any other callable can be used if ``repr()`` doesn't
    provide a unique or helpful comparison.

    The comparison is also ordering dependent. If ``qs`` doesn't provide an
    implicit ordering, you will need to apply a ``order_by()`` clause to your
    queryset to ensure that the test will pass reliably.

.. method:: TestCase.assertNumQueries(num, func, *args, **kwargs)

    .. versionadded:: 1.3

    Asserts that when ``func`` is called with ``*args`` and ``**kwargs`` that
    ``num`` database queries are executed.

    If a ``"using"`` key is present in ``kwargs`` it is used as the database
    alias for which to check the number of queries.  If you wish to call a
    function with a ``using`` parameter you can do it by wrapping the call with
    a ``lambda`` to add an extra parameter::

        self.assertNumQueries(7, lambda: my_function(using=7))

    If you're using Python 2.5 or greater you can also use this as a context
    manager::

        # This is necessary in Python 2.5 to enable the with statement, in 2.6
        # and up it is no longer necessary.
        from __future__ import with_statement

        with self.assertNumQueries(2):
            Person.objects.create(name="Aaron")
            Person.objects.create(name="Daniel")

.. _topics-testing-email:

Serviços de e-mail
------------------

Se alguma de suas views manda e-mail usando a :doc:`Funcionalidade de e-mail do
Django </topics/email>`, você provavelmente não quer mandar e-mail cada vez que
você roda um teste utilizando a view. Por esse motivo, o executor de testes do
Django automaticamente redireciona todos e-mails enviados por meio do Django
para uma caixa de saída fictícia. Isso deixa você testar cada aspecto do envio
de e-mail -- do númeto de mensagens enviadas ao conteúdo de cada mensagem -- sem
ter de enviar as mensagens de verdade.

O executor de testes consegue fazer isso de forma transparente trocando a
classe :class:`<~django.core.mail.SMTPConnection>` normal por uma versão
diferente. (Não se preocupe -- isso não tem efeito em quaisquer outros meios de
envio de e-mail fora do Django, como o servidor de e-mail de sua máquina, se
estiver rodando um).

.. currentmodule:: django.core.mail

.. data:: django.core.mail.outbox

Durante a execução dos testes, cada e-mail de saída é gravado em
``django.core.mail.outbox``. Esta é uma lista simples de todas as instâncias
de :class:`<~django.core.mail.EmailMessage>` que foram enviadas. Ela não existem
nas condições normais de execução, ou seja, quando você não está rodando testes
unitários. A caixa de saída é criada durante a configuração do teste, junto com
a :class:`<~django.core.mail.SMTPConnection>` fictícia. Quando o framework de
teste é encerrado, a classe :class:`<~django.core.mail.SMTPConnection>` padrão é
restaurada, e a caixa de saída de teste é destruída.

The ``outbox`` attribute is a special attribute that is created *only* when
the tests are run. It doesn't normally exist as part of the
:mod:`django.core.mail` module and you can't import it directly. The code
below shows how to access this attribute correctly.

Aqui vai um exemplo de teste que verifica o tamanho e conteúdo de
``django.core.mail.outbox``::

    from django.core import mail
    from django.test import TestCase

    class EmailTest(TestCase):
        def test_send_email(self):
            # Envia mensagem.
            mail.send_mail('Assunto aqui', 'Aqui vai a mensagem.',
                'from@example.com', ['to@example.com'],
                fail_silently=False)

            # Verifica se uma mensagem foi enviada.
            self.assertEqual(len(mail.outbox), 1)

            # Verifica se o assunto da mensagem é igual
            self.assertEqual(mail.outbox[0].subject, 'Assunto aqui')

Como dito :ref:`anteriormente <emptying-test-outbox>`, a caixa de saída de teste
é esvaziada no início de cada teste em um ``TestCase`` Django. Para esvaziar a
caixa de saída manualmente, atribua uma lista vazia para ``mail.outbox``::

    from django.core import mail

    # Esvazia a caixa de saída
    mail.outbox = []
    
IfDBFeature('supports_transactions')
        def test_transaction_behavior(self):
            # ... conditional test code

skipUnlessDBFeature
~~~~~~~~~~~~~~~~~~~

Skip the decorated test if the named database feature is *not*
supported.

For example, the following test will not be executed if the database
supports transactions (e.g., it would run under PostgreSQL, but *not*
under MySQL with MyISAM tables)::

    class MyTests(TestCase):
        @skipUnlessDBFeature('supports_transactions')
        def test_transaction_behavior(self):
            # ... conditional test code

Utilizando frameworks de testes diferentes
==========================================

Obviamente, ``doctest`` e ``unittest`` não são os únicos frameworks de testes
Python. Apesar de o Django não suportar explicitamente frameworks alternativos,
ele provê uma maneira de invocar testes construídos para um framework
alternativo como se fossem testes Django normais.

Quando você roda ``./manage.py test``, o Django procura a configuração
:setting:`TEST_RUNNER` para determinar o que fazer. Por padrão, o
:setting:`TEST_RUNNER` aponta para ``'django.test.simple.run_tests'``. Este
método define o comportamento padrão dos testes no Django. Esse comportamento
envolve:

    #. Fazer uma configuração global antes do teste.
    
    #. Procurar testes unitários e doctests nos arquivos ``models.py`` e
       ``tests.py`` em cada aplicação instalada.

    #. Criar o banco de dados de teste.

    #. Executar ``syncdb`` para instalar os modelos e dados iniciais no banco
       de dados de teste.

    #. Rodar os testes unitários e doctests que forem encontrados.

    #. Destruir o banco de dados de teste.

    #. Executar um encerramento global após o término dos testes.

Se você define seu próprio método executor de testes e aponta o
:setting:`TEST_RUNNER` para este método, o Django rodará o seu executor de
testes toda vez que você rodar ``./manage.py test``. Desta maneira, é possível
usar qualquer framework de testes que possa ser executado a partir de um código
Python.

.. _topics-testing-test_runner:

Definindo o executor de testes
------------------------------

.. versionchanged:: 1.2
   Prior to 1.2, test runners were a single function, not a class.

.. currentmodule:: django.test.simple

.. currentmodule:: django.test.simple

A test runner is a class defining a ``run_tests()`` method. Django ships
with a ``DjangoTestSuiteRunner`` class that defines the default Django
testing behavior. This class defines the ``run_tests()`` entry point,
plus a selection of other methods that are used to by ``run_tests()`` to
set up, execute and tear down the test suite.

.. class:: DjangoTestSuiteRunner(verbosity=1, interactive=True, failfast=True, **kwargs)

    ``verbosity`` determines the amount of notification and debug information
    that will be printed to the console; ``0`` is no output, ``1`` is normal
    output, and ``2`` is verbose output.

    If ``interactive`` is ``True``, the test suite has permission to ask the
    user for instructions when the test suite is executed. An example of this
    behavior would be asking for permission to delete an existing test
    database. If ``interactive`` is ``False``, the test suite must be able to
    run without any manual intervention.

    If ``failfast`` is ``True``, the test suite will stop running after the
    first test failure is detected.

    Django will, from time to time, extend the capabilities of
    the test runner by adding new arguments. The ``**kwargs`` declaration
    allows for this expansion. If you subclass ``DjangoTestSuiteRunner`` or
    write your own test runner, ensure accept and handle the ``**kwargs``
    parameter.

.. method:: DjangoTestSuiteRunner.run_tests(test_labels, extra_tests=None, **kwargs)

    Run the test suite.

    ``test_labels`` is a list of strings describing the tests to be run. A test
    label can take one of three forms:

        * ``app.TestCase.test_method`` -- Run a single test method in a test
          case.
        * ``app.TestCase`` -- Run all the test methods in a test case.
        * ``app`` -- Search for and run all tests in the named application.

    If ``test_labels`` has a value of ``None``, the test runner should run
    search for tests in all the applications in :setting:`INSTALLED_APPS`.

    ``extra_tests`` is a list of extra ``TestCase`` instances to add to the
    suite that is executed by the test runner. These extra tests are run
    in addition to those discovered in the modules listed in ``test_labels``.

    This method should return the number of tests that failed.

.. method:: DjangoTestSuiteRunner.setup_test_environment(**kwargs)

    Sets up the test environment ready for testing.

.. method:: DjangoTestSuiteRunner.build_suite(test_labels, extra_tests=None, **kwargs)

    Constructs a test suite that matches the test labels provided.

    ``test_labels`` is a list of strings describing the tests to be run. A test
    label can take one of three forms:

        * ``app.TestCase.test_method`` -- Run a single test method in a test
          case.
        * ``app.TestCase`` -- Run all the test methods in a test case.
        * ``app`` -- Search for and run all tests in the named application.

    If ``test_labels`` has a value of ``None``, the test runner should run
    search for tests in all the applications in :setting:`INSTALLED_APPS`.

    ``extra_tests`` is a list of extra ``TestCase`` instances to add to the
    suite that is executed by the test runner. These extra tests are run
    in addition to those discovered in the modules listed in ``test_labels``.

    Returns a ``TestSuite`` instance ready to be run.

.. method:: DjangoTestSuiteRunner.setup_databases(**kwargs)

    Creates the test databases.

    Returns a data structure that provides enough detail to undo the changes
    that have been made. This data will be provided to the ``teardown_databases()``
    function at the conclusion of testing.

.. method:: DjangoTestSuiteRunner.run_suite(suite, **kwargs)

    Runs the test suite.

    Returns the result produced by the running the test suite.

.. method:: DjangoTestSuiteRunner.teardown_databases(old_config, **kwargs)

    Destroys the test databases, restoring pre-test conditions.

    ``old_config`` is a data structure defining the changes in the
    database configuration that need to be reversed. It is the return
    value of the ``setup_databases()`` method.

.. method:: DjangoTestSuiteRunner.teardown_test_environment(**kwargs)

    Restores the pre-test environment.

.. method:: DjangoTestSuiteRunner.suite_result(suite, result, **kwargs)

    Computes and returns a return code based on a test suite, and the result
    from that test suite.

Utilitários de testes
---------------------

.. module:: django.test.utils
   :synopsis: Helpers to write custom test runners.

Para ajudar na criação de seu próprio executor de testes, o Django possui
alguns métodos utilitários no módulo ``django.test.utils``.

.. function:: setup_test_environment()

    Executa quaisquer configurações prévias aos testes, como a instalação de
    instrumentação para o sistema de templates e a configuração do
    ``SMTPConnection`` fictício.

.. function:: teardown_test_environment()

    Executa quaisquer tarefas globais de encerramento após o término dos testes,
    como remover a magia negra do sistema de templates e restaurar os serviços
    normais de e-mail.

    The creation module of the database backend (``connection.creation``) also
    provides some utilities that can be useful during testing.

.. function:: create_test_db(verbosity=1, autoclobber=False)

    Cria um novo banco de dados e roda o ``syncdb`` nele.

    ``verbosity`` tem o mesmo comportamento que em ``run_tests()``.

    ``autoclobber`` descreve o comportamento que acontecerá se um banco de dados
    com o mesmo nome que o banco de teste é encontrado:

        * Se ``autoclobber`` é ``False``, será pedido ao usuário para aprovar
          a destruição do banco de dados existente. ``sys.exit`` é chamado se
          o usuário não aprovar.

        * Se ``autoclobber`` é ``True``, o banco de dados será destruído sem
          consultar o usuário.

    Returns the name of the test database that it created.

    ``create_test_db()`` tem o efeito colateral de modificar
    ``settings.DATABASE_NAME`` para bater com o nome do banco de dados de
    teste.

.. function:: destroy_test_db(old_database_name, verbosity=1)

    Destrói o banco de dados cujo nome está no parâmetro de configuração
    :setting:`DATABASE_NAME` e restaura o valor de :setting:`DATABASE_NAME` para
    o nome fornecido.

    ``verbosity`` tem o mesmo comportamento que em ``run_tests()``.