# Premiers tests avec pytest

Un test automatique est un petit programme qui vérifie qu'un autre programme fait ce qu'on attend. On le lance en une commande, autant de fois qu'on veut.

## Le problème

Le projet n'a aucun test. Pour vérifier qu'un changement n'a rien cassé, il faut lancer le jeu, créer une partie, déplacer un colon, fonder une ville, sauvegarder, recharger. Plusieurs minutes, à refaire après chaque modification. Dans la pratique, on ne le fait pas à chaque fois, et les bugs passent.

Le bug des voisins après chargement en est l'exemple : il n'apparaît que si l'on pense à recharger une partie **puis** à déplacer une unité.

## Installer pytest

`pytest` est l'outil de test le plus utilisé en Python.

```bash
pip install pytest
```

À ajouter aussi dans `requirements.txt`.

## Un premier test

On crée un dossier `tests/` à la racine, et un fichier dont le nom commence par `test_`.

```python
# tests/test_hex.py
from hex import find_neighbors


def test_a_tile_has_six_neighbors():
    assert len(find_neighbors((3, 4))) == 6
```

On lance :

```bash
pytest
```

```text
tests/test_hex.py .                                    [100%]
1 passed in 0.01s
```

Trois règles suffisent pour commencer :

- le fichier s'appelle `test_quelquechose.py` ;
- la fonction s'appelle `test_quelquechose` ;
- `assert` suivi d'une condition : si elle est fausse, le test échoue.

## Anatomie d'un test

Un bon test se lit en trois temps.

```python
def test_neighbors_differ_on_odd_rows():
    # 1. Préparer
    even = (1, 2)
    odd = (1, 1)

    # 2. Agir
    top_right_even = find_neighbors(even)[5]
    top_right_odd = find_neighbors(odd)[5]

    # 3. Vérifier
    assert top_right_even == (1, 1)
    assert top_right_odd == (2, 0)
```

Le **nom du test** est une phrase qui décrit le comportement attendu. Quand il échoue, on sait ce qui est cassé sans ouvrir le fichier.

## Quand un test échoue

```text
    def test_distance():
>       assert hex_distance((0, 0), (2, 2)) == 3
E       assert 4 == 3
E        +  where 4 = hex_distance((0, 0), (2, 2))
```

`pytest` montre la ligne, la valeur obtenue et la valeur attendue. C'est souvent suffisant pour trouver l'erreur.

## Quoi tester en premier

Tout ne se teste pas avec la même facilité. On commence par ce qui rapporte le plus pour le moins d'effort.

<Mermaid
  chart={`flowchart TB
    a[Fonctions pures<br/>voisins, distance, A*] --> b[Règles du jeu<br/>déplacer, construire, fin de tour]
    b --> c[Sauvegarde<br/>écrire puis relire]
    c --> d[Interface<br/>clics, affichage]
    a -.- e1[Facile, très rentable]
    d -.- e2[Difficile, peu rentable]`}
/>

| Cible | Exemple de test | Difficulté aujourd'hui |
| --- | --- | --- |
| Mathématiques hexagonales | Une case a six voisins | Facile, une fois sorties de `Map` |
| Pathfinding | Le chemin contourne l'eau | Facile |
| Règles | Fonder une ville donne 7 cases | Impossible : il faut un `game` complet |
| Sauvegarde | Recharger rend le même état | Impossible pour la même raison |
| Interface | Le bouton START change de page | Très difficile |

## Pourquoi certaines choses sont impossibles à tester

Essayons de tester le déplacement d'une unité :

```python
def test_unit_moves():
    unit = Unit(game, tile, owner)   # il faut un game...
```

`Unit` demande un `game`. `Game()` ouvre une fenêtre, charge des images, lit des fichiers. Et `Unit.move` appelle l'interface.

Le test nous apprend quelque chose : **un code difficile à tester est un code trop couplé**. Ce n'est pas le test qui est en tort.

La solution n'est pas de ruser avec le test, mais de sortir les règles de l'interface. Voir [Fonctions et effets de bord](/python/bonnes-pratiques/fonctions).

## Des tests pour le jeu

### Les voisins sont réciproques

Si B est voisine de A, alors A est voisine de B. Un bon test pour attraper une erreur dans les deux listes de `find_neighbors`.

```python
def test_neighbors_are_mutual():
    for coo in [(0, 0), (3, 4), (5, 7), (2, 1)]:
        for n in find_neighbors(coo):
            assert coo in find_neighbors(n)
```

### La distance

```python
def test_distance_to_self_is_zero():
    assert hex_distance((3, 4), (3, 4)) == 0


def test_neighbors_are_at_distance_one():
    for n in find_neighbors((3, 4)):
        assert hex_distance((3, 4), n) == 1
```

### Plusieurs cas d'un coup

`parametrize` lance le même test avec plusieurs jeux de valeurs.

```python
import pytest


@pytest.mark.parametrize("a, b, expected", [
    ((0, 0), (0, 0), 0),
    ((0, 0), (1, 0), 1),
    ((0, 0), (2, 2), 3),
])
def test_hex_distance(a, b, expected):
    assert hex_distance(a, b) == expected
```

### Reproduire un bug avant de le corriger

La bonne habitude : quand on trouve un bug, on écrit **d'abord** le test qui le montre. Il échoue. On corrige. Il passe. Et le bug ne reviendra pas sans qu'on le sache.

```python
def test_coordinates_survive_a_save():
    saved = json.loads(json.dumps([(3, 4), "plain", []]))
    coo = load_coo(saved)
    assert coo == (3, 4)
    assert coo in find_neighbors((2, 4))
```

## Maîtriser le hasard

La carte est générée au hasard : deux lancements donnent deux résultats. Un test doit être **reproductible**. On fixe la graine du générateur :

```python
import random


def test_map_has_expected_size():
    random.seed(42)
    world = generate_world(layers=7)
    assert len(world.tiles_by_coo) == 127
```

Avec la même graine, `randint` rend toujours la même suite.

## Organiser les tests

```text
BestGameOfTheYear/
├── src/
│   ├── hex.py
│   └── ...
├── tests/
│   ├── test_hex.py
│   ├── test_pathfinding.py
│   └── test_commands.py
└── pytest.ini
```

Pour que les tests trouvent le code de `src/`, un fichier `pytest.ini` à la racine :

```text
[pytest]
pythonpath = src
testpaths = tests
```

Commandes utiles :

| Commande | Effet |
| --- | --- |
| `pytest` | Lance tous les tests |
| `pytest tests/test_hex.py` | Un seul fichier |
| `pytest -k distance` | Les tests dont le nom contient « distance » |
| `pytest -x` | S'arrête au premier échec |
| `pytest -v` | Affiche le nom de chaque test |

## Ce qu'un test ne fait pas

- Il ne prouve pas l'absence de bug, seulement que les cas prévus fonctionnent.
- Il ne remplace pas le fait de jouer au jeu.
- Trop de tests sur des détails rendent le code pénible à modifier. On teste **le comportement**, pas la façon dont il est obtenu.

## À retenir

- Un test : préparer, agir, vérifier.
- Commencer par les fonctions pures.
- Un code impossible à tester est un code trop couplé.
- Un bug trouvé, un test écrit.
- Fixer la graine quand il y a du hasard.

## Exercices

1. Installer `pytest`, créer `tests/test_hex.py`, et faire passer le test des six voisins. Il faudra d'abord sortir `find_neighbors` de `Map`.
2. Écrire le test de réciprocité des voisins.
3. Écrire `hex_distance` en commençant par ses tests. Voir A* sur la grille hexagonale (documentation du jeu).
4. Écrire un test qui échoue à cause du bug des coordonnées après chargement, puis corriger le bug.
