---
title: Configurer Claude Code
description: Créez un workspace d'écriture de tests Kapptivate avec ktm init et connectez-le à Claude Code.
sidebarTitle: Claude Code
lastUpdated: "2026-07-20"
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

Écrire un test Kapptivate à la main suppose de connaître la grammaire JSON, le catalogue d'actions et les sélecteurs qui fonctionnent réellement sur votre application. `ktm init` crée un workspace qui confie tout cela à Claude Code : les skills d'écriture, un catalogue de vos tests et variables, et une connexion vivante à un robot capable de piloter de vrais navigateurs et appareils.

Cette page décrit la configuration pour Claude Code. Le même workspace fonctionne dans Cursor, Codex et Copilot sans modification.

## Avant de commencer

Il vous faut `ktm` installé et une clé API. Si ce n'est pas encore le cas, suivez d'abord [Installation](/fr/cli/installation), puis créez une clé depuis les Paramètres de votre organisation, rubrique Clés API.

## Créer le workspace

Créez un dossier vide et lancez l'assistant dedans. Un dossier correspond aux tests d'un produit.

```bash
mkdir mes-tests
cd mes-tests
ktm init
```

L'assistant demande votre environnement, votre clé API, l'opérateur et le produit ciblés, et le robot à piloter. Appuyez sur Entrée pour accepter la valeur par défaut à tout moment.

Claude Code ne demande aucune réponse à la question sur les agents de code : `ktm init` le configure systématiquement. Il écrit `.mcp.json` pour la connexion au robot et ajoute le serveur à `.claude/settings.local.json` pour que Claude Code l'active réellement.

À la fin, vous obtenez un dossier de cette forme :

```
mes-tests/
  .agents/skills/          les skills d'écriture, fichiers réels
  .claude/skills/          liens vers ces skills, lus par Claude Code
  .mcp.json                connexion au robot
  CLAUDE.md                contrat du workspace pour Claude Code
  AGENTS.md                le même contrat pour les autres agents
  catalog/                 instantané de vos tests, variables et réutilisables
  pages/                   sélecteurs vérifiés lors d'une exécution réelle
  .ktm.json                opérateur et produit ciblés par ce dossier
```

<Note>
  Les fichiers porteurs d'un secret (`.mcp.json`, `.ktm.local.json`) sont ajoutés au `.gitignore` automatiquement. Le dossier peut être versionné tel quel.
</Note>

## Lancer Claude Code dans le dossier

```bash
cd mes-tests
claude
```

Claude Code lit `CLAUDE.md`, `.mcp.json` et `.claude/skills/` relativement au dossier de lancement. Démarrer depuis un dossier parent ne les prendra pas en compte.

Si Claude Code tournait déjà dans ce dossier, redémarrez-le ou lancez `/mcp`, sinon il ne verra pas le serveur qui vient d'être ajouté.

## Vérifier la connexion au robot

Lancez `/mcp` dans Claude Code. `kapptivate-automation` doit apparaître comme connecté.

S'il est absent ou en échec, le robot n'est probablement pas joignable. Vérifiez qu'il est en ligne, puis lancez `ktm init --reconfigure` pour le récupérer.

## Remplir le catalogue

Les skills sont disponibles en commandes slash. Lancez celui-ci en premier :

```
/sync-kapptivate-catalog
```

Il récupère vos tests, variables et réutilisables dans `catalog/`, ce qui permet à Claude de référencer un groupe de variables existant par son id au lieu d'écrire un mot de passe en dur.

Rafraîchissez-le dès que le catalogue dépasse une quinzaine de jours, ou après une modification des tests sur la plateforme.

## Écrire votre premier test

Demandez en langage courant, ou partez directement du skill.

```
/write-kapptivate-test un test qui se connecte à la boutique avec les
identifiants de staging et vérifie que la page compte affiche le nom
de l'utilisateur
```

Claude rédige le test, l'exécute sur un vrai navigateur via le robot, et corrige ce qui échoue. Un test n'est pas terminé tant qu'il ne renvoie pas `success` : la validation structurelle ne détecte pas un mauvais sélecteur, seule une exécution réelle le fait.

<Tip>
  Après une exécution verte, demandez à Claude d'enregistrer dans `pages/` les sélecteurs qu'il a vérifiés. Le test suivant sur les mêmes écrans partira de sélecteurs éprouvés au lieu de les redécouvrir.
</Tip>

## Maintenir le workspace à jour

Les skills sont verrouillés sur la version du CLI : ils documentent les options et le comportement du binaire qui les a écrits. Après une mise à jour de `ktm`, rafraîchissez-les.

```bash
ktm update
ktm init --refresh-skills
```

<Warning>
  `--refresh-skills` supprime et réécrit les dossiers de skills. Si vous y conservez des fichiers personnels, prévisualisez d'abord avec `ktm init --refresh-skills --dry-run`, qui liste tout ce qui serait supprimé.
</Warning>

## Partager le workspace avec un collègue sous Windows

`.claude/skills/` contient des liens vers `.agents/skills/`, et git les stocke comme des liens symboliques. Un checkout Windows sans prise en charge des liens matérialise chacun d'eux en un petit fichier texte contenant un chemin : Claude Code trouve alors un fichier là où il attend un dossier de skill.

Le correctif tient en une commande, à lancer une fois après le clone :

```bash
ktm init --refresh-skills
```

Sur un hôte Windows incapable de créer des liens, cette commande écrit de vraies copies à la place, et tout fonctionne à partir de là.

<Note>
  Cursor et Codex ne sont pas concernés : ils lisent `.agents/skills/`, qui contient toujours de vrais fichiers. Cela ne touche que Claude Code, et seulement sur un clone Windows d'un workspace versionné ailleurs.
</Note>

## Résolution de problèmes

<AccordionGroup>
  <Accordion title="Les commandes slash n'apparaissent pas">
    Claude Code les lit dans `.claude/skills/` relativement au dossier de lancement. Vérifiez que vous avez démarré dans le dossier créé, et non son parent, puis redémarrez la session.
  </Accordion>
  <Accordion title="/mcp ne liste pas kapptivate-automation">
    Le serveur est déclaré dans `.mcp.json` mais Claude Code l'active via `.claude/settings.local.json`. Si vous avez refusé l'activation à un moment, lancez `ktm init --reconfigure` pour la rétablir, puis redémarrez Claude Code.
  </Accordion>
  <Accordion title="Le robot se connecte mais les commandes échouent en 401">
    La clé API atteint la plateforme mais pas le robot. Lancez `ktm operators list` puis `ktm reusables list --product <operateur>~<produit>`. Si la seconde échoue, votre clé n'a pas les accès au niveau produit : créez une nouvelle clé sur une équipe qui les possède.
  </Accordion>
  <Accordion title="ktm init indique qu'aucun robot n'a répondu">
    Aucun agent d'automatisation n'était en ligne pour votre opérateur au moment de l'assistant. `.mcp.json` conserve une URL de remplacement. Lancez `ktm init --reconfigure` une fois un robot démarré, ou passez `--automation-url <endpoint>` si vous la connaissez.
  </Accordion>
</AccordionGroup>

## Et ensuite ?

<Columns cols={2}>
  <Card title="Configurer Cursor" icon="arrow-pointer" href="/fr/cli/agents/cursor">

    Le même workspace, configuré pour Cursor

</Card>
  <Card title="Écrire des tests avec un agent" icon="wand-magic-sparkles" href="/fr/cli/guides/create-tests">

    Approfondir le prompting, les sélecteurs et l'obtention d'un test vert

</Card>
  <Card title="Configuration du CLI" icon="gear" href="/fr/cli/configuration">

    Variables d'environnement, hôtes et stockage des identifiants

</Card>
  <Card title="Exécuter les tests en CI" icon="rocket" href="/fr/cli/ci-cd">

    Emmener les tests écrits ici dans votre pipeline

</Card>
</Columns>