Diagnostiquer une exécution feint quand un test échoue

Quand un test échoue contre feint, la première question n'est pas « pourquoi », c'est « où ». Le problème vient de l'hôte, de l'émulateur ou de votre client, et quatre commandes séparent ces trois cas en moins d'une minute. Cette page les prend dans l'ordre où elles coûtent le moins cher.

Ce que vous allez obtenir

À la fin de cette page, vous saurez situer une panne en quatre commandes : doctor pour l'hôte, status pour l'émulateur, logs et le journal des appels pour ce que votre client a réellement envoyé.

Choisir la commande qui répond à la question que vous vous posez.
Lire un rapport de diagnostic et trier l'avertissement du blocage.
Repérer une configuration capable de joindre le vrai cloud malgré tout.
Brancher les codes de sortie dans un script d'intégration continue.

Quelle commande pour quelle question

Chaque commande répond à une question, et les confondre fait perdre du temps. Ce tableau est le raccourci à retenir.

Votre question	La commande	Ce qu'elle regarde
Ma machine peut-elle faire tourner ça ?	`feint doctor`	le port, le runtime, les clients, les pièges SSH
Est-ce que ça tourne, et depuis quand ?	`feint status`	le processus, l'inventaire, les routes pilotées
Qu'a fait l'émulateur au démarrage ?	`feint logs`	la sortie du processus détaché
Qu'a envoyé mon client, exactement ?	`/_feint/trace`	les échanges HTTP, méthode, chemin, statut
Puis-je continuer dans un script ?	`feint wait`	l'attente qui échoue franchement

`feint doctor` : ce que votre machine sait livrer

La commande n'interroge pas l'émulateur, elle interroge l'hôte. Elle s'exécute donc avant de démarrer quoi que ce soit, et son intérêt est de transformer un échec futur et obscur en ligne lisible tout de suite.

feint doctor

Rapport de diagnostic de feint 0.13.0 : port libre, descriptions d'API trouvées, runtime incus-ovn avec ses capacités, clients officiels détectés, et l'avertissement sur le ProxyJump SSH

Trois familles de lignes se distinguent, et leur gravité n'est pas la même.

Les lignes de capacité disent ce que le runtime machine sait faire, et elles se lisent comme des faits plutôt que comme un score : addresses true, firewall true, isolation true, own kernel false. La dernière valeur explique pourquoi un test de module noyau échouera dans un conteneur : il partage le noyau de l'hôte. Ces mêmes capacités sont interrogeables par un script sur /_feint/health.

Les lignes d'outillage listent les clients officiels trouvés avec leur version et leur chemin. C'est ce qui permet de comprendre, une fois sur deux, pourquoi un script de test échoue chez un collègue : ce n'est pas l'émulateur, c'est un octl absent du PATH.

Les avertissements ne bloquent rien mais annoncent un échec probable. Le plus utile est celui du ProxyJump : une règle qui vise 10.* dans votre ~/.ssh/config capture la plage privée du runtime, et la connexion meurt sur timed out during banner exchange alors que le serveur SSH tourne. Sans cette ligne, la recherche prend une heure.

Le piège que doctor trouve avant vous

Une exécution présentée comme locale peut quand même joindre le vrai cloud. C'est la limite la plus importante de tout émulateur d'API, et elle n'a rien d'hypothétique : le provider Terraform de Scaleway code en dur l'adresse s3.<région>.scw.cloud pour le stockage objet, donc ces appels partent chez le fournisseur avec les identifiants que porte l'exécution.

Lancé depuis le répertoire de votre configuration, feint doctor lit vos fichiers Terraform et le dit avant l'apply :

warn  this Terraform configuration can reach the real scaleway cloud
      → this configuration carries scaleway_object_* (Object Storage): the
        Terraform provider hardcodes https://s3.<region>.scw.cloud for that
        product, so those calls leave for the real cloud with whatever
        credentials the run holds

Sur une configuration sans ressource de ce type, la même commande répond, et la seconde ligne est aussi importante que la première :

ok    no known escape signature in the 1 Terraform file(s) here
      this checks the measured list (docs/limits.md), not every path a client
      could compose

Le contrôle porte sur une liste mesurée, pas sur tous les chemins possibles. Un client peut toujours composer lui-même une adresse hors du périmètre émulé. Ce que cette ligne vous donne est la couverture des cas connus, ce qui est beaucoup, et elle ne prétend pas à plus. Les autres frontières de ce genre sont rassemblées dans Ce que feint prouve.

`feint status` : ce qui tourne, et ce qu'un client a piloté

La commande répond en trois blocs qui se lisent de haut en bas.

feint status

running on 127.0.0.1:4599 (pid 3861417, since 2026-08-29T17:31:22Z)
  resources  0
  machines   none

  provider    routes  driven by a client
  scaleway       193  0
  exoscale       104  0
  outscale       100  0

La colonne driven by a client est celle qui débloque le plus de situations. Elle compte les routes qu'un vrai client a réellement appelées depuis le démarrage. Un zéro alors que vous venez de lancer terraform apply signifie que votre client ne parle pas à cet émulateur : mauvaise adresse, mauvais port, ou variables d'environnement posées dans un autre shell. Le problème est chez le client, et vous venez de l'établir sans lire une ligne de journal.

La ligne machines dit si un runtime est branché. À none, l'émulateur est un plan de contrôle : il répond, et rien ne tourne. C'est le mode par défaut, et c'est ce qui permet aux tests de s'exécuter sur un runner sans rien installer.

Les journaux, et le journal des appels

Ce sont deux sources différentes, et confondre les deux fait chercher au mauvais endroit.

feint logs montre la sortie du processus détaché, donc ce que l'émulateur a fait de lui-même : les routes montées par pack, l'adresse d'écoute, la version.

feint logs | tail -6

feint v0.13.0 listening on 127.0.0.1:4599
  scaleway  193 routes
  outscale  100 routes
  exoscale  104 routes
  machines  none
  page      http://127.0.0.1:4599/_feint/ui

Le journal des appels montre ce que votre client a envoyé, et c'est la source qui tranche une question de nommage d'opération :

curl -s localhost:4599/_feint/trace \
  | jq -r '.exchanges[] | "\(.method) \(.path) \(.status) \(.operation // "aucune route")"'

GET /v2/instance-type 200 exoscale/v2.list-instance-types
GET /v2/zone 200 exoscale/v2.list-zones
GET /v2/quota 200 exoscale/v2.list-quotas

Une ligne marquée aucune route est le diagnostic le plus direct qui soit : le client a appelé un chemin que personne ne sert. La même information est lisible à l'écran sur la page d'introspection, décrite dans Mesurer la fidélité.

Les codes de sortie, et le verbe qui barre le passage

C'est la partie qui compte dans un script, et elle repose sur une distinction volontaire.

Code	Sens
`0`	tout va bien
`1`	erreur
`2`	dérive détectée, pour les commandes de fidélité

feint status sort toujours à 0, y compris quand rien ne tourne, parce qu'un émulateur arrêté est un fait et non un échec. Le verbe qui barre le passage est feint wait :

feint wait --timeout 5s

feint: 127.0.0.1:4599 did not answer within 5s

Le code de sortie vaut alors 1, et c'est ce qui fait échouer l'étape d'un pipeline plutôt que de laisser la suite s'exécuter contre un émulateur absent. Mettre status à la place de wait produit l'erreur inverse : le pipeline continue et casse quinze lignes plus loin, sur un message sans rapport. La forme correcte est détaillée dans Tester dans un pipeline.

Symptôme, cause, solution

Symptôme	Cause probable	Solution
`terraform apply` bloque puis accuse le provider	L'endpoint pointe un port muet	`feint status`, puis corriger `endpoint` dans la configuration
`driven by a client` reste à 0	Le client parle à une autre adresse	Rejouer `eval "$(feint env <fournisseur>)"` dans ce shell
`feint start` refuse de démarrer	Un émulateur occupe déjà le port	`feint stop`, ou `feint status` pour vérifier lequel
SSH meurt sur `banner exchange`	Un `ProxyJump` capture la plage privée	Restreindre le motif `Host`, ou `ssh -F /dev/null`
`warn no contracts/ directory here`	Les réponses ne sont pas vérifiées contre les descriptions d'API	Lancer depuis le dépôt, ou passer `--contracts <dossier>`
Un test passe puis échoue au suivant	Une règle de panne est restée armée	`curl -X DELETE localhost:4599/_feint/faults`
Une opération répond `404` sans raison apparente	Le pack décline cette opération	Vérifier l'en-tête `X-Feint-Not-Emulated` de la réponse

Quand l'émulateur ne sert pas une opération, il ajoute X-Feint-Not-Emulated: <pack> à la réponse. C'est ce qui permet de distinguer un refus de service d'une ressource absente, deux situations qui portent parfois le même code HTTP. Aucun vrai cloud n'envoie cet en-tête, donc aucun client ne peut s'y perdre.

curl -si localhost:4599/v2/reverse-dns/instance/inexistante | grep -i x-feint

À retenir

Situer avant d'expliquer : hôte, émulateur ou client, dans cet ordre.
doctor interroge la machine, pas l'émulateur, et se lance avant le démarrage.
Lancé dans un répertoire Terraform, doctor signale les configurations capables de joindre le vrai cloud.
driven by a client à zéro signifie que votre client parle ailleurs.
status sort toujours à 0 ; le verbe qui fait échouer un pipeline est wait.
X-Feint-Not-Emulated distingue une opération déclinée d'une ressource absente.

Prochaines étapes

Provoquer une panne exprès Armer un 503 ou un timeout et regarder comment votre client réagit.

Tester dans un pipeline Les codes de sortie et l'attente, dans GitHub Actions et GitLab CI.

Ce que feint prouve La matrice des verdicts, et les limites que le diagnostic signale.

Mesurer la fidélité La page d'introspection, le journal des appels et les snapshots.