Skip to content

Latest commit

 

History

History
223 lines (153 loc) · 7.16 KB

outils.md

File metadata and controls

223 lines (153 loc) · 7.16 KB

Outils de développement

Migrations

Les migrations de la base de données sont gérées avec alembic.

Pour appliquer les migrations en attente :

make migrate

Pour créer une nouvelle migration :

name=create-some-table make migration

Pour voir l'état actuel des migrations :

make currentmigration

Données initiales

Pour l'utilisation dans les environnements de déploiement, voir Opérations - Données initiales.

Le script tools/initdata.py permet de définir des données initiales à charger en base.

Il peut être lancé comme suit :

make initdata

Des entités seront ainsi chargées en base de données.

Si celles-ci ont changé (suite à des manipulations manuelles dans le frontend, par exemple) et que vous souhaitez les remettre dans leur état initial, lancer :

make initdatareset

Ces commandes make sont branchées sur le fichier tools/initdata.yml. Pour utiliser un fichier différent, invoquer le script Python directement :

venv/bin/python -m tools.initdata <file>

La structure d'un fichier d'initdata est ad-hoc, et fortement corrélée au traitement réalisé par le script.

Structure :

  • users - list
    • id - str - UUID
    • params - dict
      • email - str
      • password - str - Utiliser __env__ pour tirer le mot de passe de TOOLS_PASSWORDS
    • extras - Optionnel, dict
      • role - str, USER | ADMIN
  • tags - list
    • id - str - UUID
    • params - dict
      • name - str
  • datasets - list

Il est possible de passer des mots de passe utilisateur secrets en utilisant la valeur spéciale password: __env__. Le mot de passe correspondant à l'email doit alors être défini dans un objet JSON via la variable d'environnement TOOLS_PASSWORD :

TOOLS_PASSWORDS='{"email1": "password1", "email2": "password2", ...}' venv/bin/python -m tools.initdata /path/to/initdata.yml

Exemple :

users:
  - # Utilisateur standard.
    id: "<UUID>"
    params:
      email: "[email protected]"
      password: "example"
  - # Utilisateur admin.
    # Mot de passe défini par $TOOLS_PASSWORDS, ou demandé en ligne de commande si vide.
    id: "<UUID>"
    params:
      email: "[email protected]"
      password: __env__
    extras:
      role: ADMIN
  - # ...

tags:
  - id: "<UUID>"
    params:
      name: "<name>"
  - # ...

datasets:
  - id: "<UUID>"
    params:
      title: "<title>"
      description: "<description>"
      formats:
        - "<format>"
      # ...
  - # ...

Utilisation :

TOOLS_PASSWORDS='{"[email protected]": "sarahpwd"}' venv/bin/python -m tools.initdata /path/to/initdata.yml

N.B. : Avant de créer chaque entité, le script s'assure qu'elle n'existe pas déjà en base. En passant le flag --reset (intégré dans make initdatareset), les champs des entités existantes sont réinitialisées à leurs valeurs définies dans le fichier YAML.

Pour plus de détails, lire le code source.

Jeux de données aléatoires

Il est possible d'ajouter un paquet de jeux de données aléatoires au catalogue d'une organisation de cette façon:

siret=... make randomdatasets

Par défaut 500 jeux de données sont ajoutés. Pour en ajouter une autre quantité, utiliser :

siret=... n=... make randomdatasets

Générer un UUID

Pour générer un UUID d'entité, lancer :

make id

Exemple de sortie :

9355b423-4417-4153-8fd6-524697f8c88f

Diagramme de la base de données

Le fichier docs/db.erd.json permet de générer un diagramme du schéma de la base de données.

Pour cela, installer d'abord graphviz (sous Linux : $ sudo apt install graphviz).

Puis lancer :

make dbdiagram

Ce qui génèrera docs/db.png.

Le format de docs/db.erd.json reprend celui de erdot, dont la documentation peut donc vous être utile.

mypy

Ce projet est équipé du type checking avec mypy.

La vérification se fait avec une exécution standard de $ mypy lors de make check.

Tests

Tests E2E

Les tests end-to-end sont lancés avec Playwright. Il sont soit exécutés en mode ci (continuous integration, par exemple dans notre cas avec github actions), et donc en headless, soit de manière interactive (en dev).

Astuces

  • Pour lancer Playwright en mode headed (affichage du navigateur au fur et à mesure des tests), modifier temporairement headless: false dans le fichier client/playwright.config.ts. Voir Headed mode.
  • Pour lancer Playwright en mod debug (affichage du navigateur + console de débogage), lancer PWDEBUG=1 make test-client-e2e-ci. Il sera peut-être demandé d'installer Chromium : utiliser cd client && npx playwright install chromium. Voir aussi Debugging tests.
  • Pour lancer un test en particulier, modifier temporairement test(...) en test.only(...). Voir Focus a test.

Tests unitaires - Client

Les tests unitaires côté client utilisent svelte-testing-library.

Autres ressources pour démarrer :

Astuces

  • Utiliser cd client && npm run test:watch pour lancer les tests en mode "watch" : les tests seront relancés automatiquement au fur et à mesure que vous modifiez le code. Très pratique pour itérer rapidement sur des tests unitaires.

DSFR

Le site utilise le Design System de l'État (aussi appelé DSFR).

Il existe aussi le site très pratique de Démo du design système de l'état pour la mise en œuvre et l'utilisation de ce DSFR.

Icônes supplémentaires

Le DSFR tire ses icônes de RemixIcon, mais seule une partie est incluse (pour des raisons de poids).

Des icônes supplémentaires utilisées dans ce projet sont fournies par un fichier CSS client/src/styles/dsfr-icon-extras.css. Celui-ci est généré par le script tools/iconextras.py.

Pour ajouter de nouvelles icônes supplémentaires :

  • Récupérer le SVG (24px) sur https://remixicon.com/
  • Ajouter le fichier SVG au dossier client/src/assets/icon/dsfr-icon-extras/
    • Important : retirer toute éventuelle propriété fill="none". Le SVG ne doit contenir que le tracé, de sorte à être librement manipulable par CSS.
  • Lancer $ make dsfr-icon-extras pour synchroniser le CSS.
  • Utiliser les icônes comme d'habitude, mais avec fr-icon-x-<name> (x pour "extra") au lieu de fr-icon-<name>.