Teste #

Matplotlib usa a estrutura pytest .

Os testes estão em lib/matplotlib/tests, e as personalizações para a infraestrutura de teste pytest estão em matplotlib.testing.

Requisitos #

Para executar os testes, você precisará configurar o Matplotlib para desenvolvimento . Observe em particular as dependências adicionais para teste.

Observação

Assumiremos que você deseja executar os testes em uma configuração de desenvolvimento.

Embora você possa executar os testes em uma versão regular instalada do Matplotlib, esse é um caso de uso muito menos comum. Você ainda precisa das dependências adicionais para teste. Você também precisa obter as imagens de referência do repositório, porque elas não são distribuídas com pacotes Matplotlib pré-construídos.

Executando os testes #

No diretório raiz do seu repositório de desenvolvimento, execute:

python -m pytest

O pytest pode ser configurado por meio de vários parâmetros de linha de comando . Alguns particularmente úteis são:

`-v`ou`--verbose`	Seja mais prolixo
`-n NUM`	Execute testes em paralelo em NUM processos (requer pytest-xdist )
`--capture=no`ou`-s`	Não capture stdout

Para executar um único teste na linha de comando, você pode fornecer um caminho de arquivo, opcionalmente seguido pela função separada por dois pontos, por exemplo, (os testes não precisam ser instalados, mas o Matplotlib deve ser):

pytest lib/matplotlib/tests/test_simplification.py::test_clipping

Escrevendo um teste simples #

Muitos elementos do Matplotlib podem ser testados usando testes padrão. Por exemplo, aqui está um teste de matplotlib/tests/test_basic.py:

def test_simple():
    """
    very simple example test
    """
    assert 1 + 1 == 2

O Pytest determina quais funções são testes procurando por arquivos cujos nomes começam com "test_"e, dentro desses arquivos, por funções que começam com "test"ou classes que começam com "Test".

Alguns testes possuem efeitos colaterais internos que precisam ser limpos após sua execução (como figuras criadas ou modificadas rcParams). O acessório pytest matplotlib.testing.conftest.mpl_test_settingsirá limpá-los automaticamente; não há necessidade de fazer mais nada.

Dados aleatórios em testes #

Dados aleatórios são uma maneira muito conveniente de gerar dados para exemplos, porém a aleatoriedade é problemática para testes (já que os testes devem ser determinísticos!). Para contornar isso, defina a semente em cada teste. Para o gerador de números aleatórios padrão do numpy, use:

import numpy as np
rng = np.random.default_rng(19680801)

e, em seguida, use rngao gerar os números aleatórios.

A semente é o aniversário de John Hunter.

Escrevendo um teste de comparação de imagem #

Escrever um teste baseado em imagem é apenas um pouco mais difícil do que um teste simples. A principal consideração é que você deve especificar a "linha de base" ou imagens esperadas no image_comparison decorador. Por exemplo, este teste gera uma única imagem e a testa automaticamente:

from matplotlib.testing.decorators import image_comparison
import matplotlib.pyplot as plt

@image_comparison(baseline_images=['line_dashes'], remove_text=True,
                  extensions=['png'])
def test_line_dashes():
    fig, ax = plt.subplots()
    ax.plot(range(10), linestyle=(0, (3, 3)), lw=5)

Na primeira vez que esse teste for executado, não haverá imagem de linha de base para comparação, portanto, o teste falhará. Copie as imagens de saída (neste caso result_images/test_lines/test_line_dashes.png) para o subdiretório correto da baseline_imagesárvore no diretório de origem (neste caso lib/matplotlib/tests/baseline_images/test_lines). Coloque este novo arquivo sob controle de revisão do código-fonte (com ). Ao executar novamente os testes, eles agora devem passar.git add

As imagens de linha de base ocupam muito espaço no repositório Matplotlib. Uma abordagem alternativa para testes de comparação de imagens é usar o check_figures_equaldecorator, que deve ser usado para decorar uma função usando dois Figureparâmetros e desenha as mesmas imagens nas figuras usando dois métodos diferentes (o método testado e o método da linha de base). O decorador providenciará a montagem das figuras e depois coletará os resultados sorteados e os comparará.

Consulte a documentação de image_comparisone check_figures_equalpara obter informações adicionais sobre seu uso.

Criando um novo módulo em matplotlib.tests #

Tentamos manter os testes categorizados pelo módulo principal que estão testando. Por exemplo, os testes relacionados ao mathtext.pymódulo estão em test_mathtext.py.

Usando ações do GitHub para CI #

O GitHub Actions é um sistema de CI hospedado "na nuvem".

O GitHub Actions é configurado para receber notificações de novos commits para repositórios do GitHub e para executar compilações ou testes quando vê esses novos commits. Ele procura arquivos YAML .github/workflowspara ver como testar o projeto.

O GitHub Actions já está ativado para o repositório principal do Matplotlib GitHub -- por exemplo, consulte os fluxos de trabalho de testes .

As ações do GitHub devem ser ativadas automaticamente para seu fork pessoal do Matplotlib assim que os arquivos de fluxo de trabalho YAML estiverem nele. Geralmente não é necessário examinar esses fluxos de trabalho, pois qualquer solicitação pull enviada ao repositório principal do Matplotlib será testada. O fluxo de trabalho de testes é ignorado em repositórios bifurcados, mas você pode acionar uma execução manualmente na interface da web do GitHub .

Você pode ver os resultados do GitHub Actions em https://github.com/your_GitHub_user_name/matplotlib/actions -- aqui está um exemplo .

Usando tox #

Tox é uma ferramenta para executar testes em vários ambientes Python, incluindo várias versões do Python (por exemplo, 3.7, 3.8) e até mesmo diferentes implementações do Python (por exemplo, CPython, PyPy, Jython etc.), desde que todas essas versões sejam disponíveis no $PATH do seu sistema (considere usar o gerenciador de pacotes do sistema, por exemplo, apt-get, yum ou Homebrew, para instalá-los).

tox facilita determinar se sua cópia de trabalho introduziu alguma regressão antes de enviar uma solicitação pull. Veja como usá-lo:

$ pip install tox
$ tox

Você também pode executar tox em um subconjunto de ambientes:

$ tox -e py38,py39

O Tox processa tudo em série, então pode demorar muito para testar vários ambientes. Para acelerar, você pode tentar usar uma nova versão paralelizada do tox chamada detox. Experimente:

$ pip install -U -i http://pypi.testrun.org detox
$ detox

Tox é configurado usando um arquivo chamado tox.ini. Você pode precisar editar este arquivo se quiser adicionar novos ambientes para testar (por exemplo, py33) ou se quiser ajustar as dependências ou a maneira como os testes são executados. Para obter mais informações sobre o tox.iniarquivo, consulte a especificação de configuração Tox .

Construindo versões antigas do Matplotlib #

Ao executar um para ver qual commit introduziu um determinado bug, você pode (raramente) precisar construir versões muito antigas do Matplotlib. As seguintes restrições devem ser levadas em consideração:git bisect

Matplotlib 1.3 (ou anterior) requer numpy 1.8 (ou anterior).

Testando versões lançadas do Matplotlib #

Executar os testes em uma instalação de uma versão lançada (por exemplo, pacote PyPI ou pacote conda) também requer configuração adicional.

Observação

Para um usuário final, geralmente não há necessidade de executar os testes nas versões lançadas do Matplotlib. Os lançamentos oficiais são testados antes da publicação.

Instalar dependências adicionais #

Instale as dependências adicionais para teste .

Obtenha as imagens de referência #

Muitos testes comparam o resultado do gráfico com as imagens de referência. As imagens de referência não fazem parte das versões empacotadas regulares (pip wheels ou pacotes conda). Se você deseja executar testes com imagens de referência, precisa obter as imagens de referência correspondentes à versão do Matplotlib que deseja testar.

Para fazer isso, baixe a distribuição de origem correspondente matplotlib-X.Y.Z.tar.gzdo PyPI ou, alternativamente, clone o repositório git e o arquivo . Copie a pasta para a pasta da instalação do matplotlib para testar. A pasta de destino correta pode ser encontrada usando:git checkout vX.Y.Zlib/matplotlib/tests/baseline_imagesmatplotlib/tests

python -c "import matplotlib.tests; print(matplotlib.tests.__file__.rsplit('/', 1)[0])"

Uma cópia análoga de lib/mpl_toolkits/tests/baseline_images é necessária para testar mpl_toolkits.

Execute os testes #

Para executar todos os testes em sua versão instalada do Matplotlib:

python -m pytest --pyargs matplotlib.tests

O escopo de descoberta de teste pode ser reduzido a módulos de teste únicos ou até funções únicas:

python -m pytest --pyargs matplotlib.tests.test_simplification.py::test_clipping