@duplojs/agents-kit 0.0.0-stage → 0.1.0-beta.10

package/docs/API/60-playwright/10-construction/10-initClient.ts

@@ -0,0 +1,38 @@
+/**
+ * @title Initialiser un client de test Playwright
+ *
+ * Étendre le client Playwright avec une fixture Website DuploJS utilisable dans les tests.
+ */
+import { createPage, createWebsite, type Website } from "@duplojs/playwright";
+import test from "playwright/test";
+
+interface TestFixtures {
+	website: Website;
+}
+
+// Playwright fournit une page et un contexte isolés pour chaque test.
+export const testClient = test.extend<TestFixtures>({
+	async website({ page, context }, use) {
+		const website = createWebsite({
+			playwrightPage: page,
+			playwrightBrowserContext: context,
+			envConfig: {
+				baseUrl: "http://localhost:3000",
+			},
+		});
+
+		// La fixture met le Website à disposition pendant le test.
+		await use(website);
+	},
+});
+
+const homePage = createPage("home", {
+	makePath: () => "/",
+	getMainElement: ({ body }) => body.locator("main"),
+});
+
+// Les tests importent testClient et reçoivent la fixture typée parmi les fixtures Playwright.
+testClient("le site affiche son titre", async({ website }) => {
+	await website.iNavigateTo(homePage);
+	await website.iExpectTitleIs(/Accueil/);
+});

package/docs/API/60-playwright/10-construction/index.llms.md

@@ -0,0 +1,28 @@
+## Construction
+
+Fabriques de sites, pages, composants, interactions et wrappers de parcours.
+
+### [createComponent](10-createComponent.ts)
+
+Définir une zone réutilisable et ses éléments, méthodes et composants enfants.
+ 
+### [createComponentInteraction](10-createComponentInteraction.ts)
+
+Créer une interaction typée sur un élément nommé et une étape Playwright.
+ 
+### [createPage](10-createPage.ts)
+
+Définir un écran navigable et son chemin typé.
+ 
+### [createStepWrapper](10-createStepWrapper.ts)
+
+Envelopper des interactions dans une étape Playwright personnalisée.
+ 
+### [createWebsite](10-createWebsite.ts)
+
+Construire le contexte du site et naviguer ou vérifier ses pages et composants.
+ 
+### [Initialiser un client de test Playwright](10-initClient.ts)
+
+Étendre le client Playwright avec une fixture Website DuploJS utilisable dans les tests.
+ 

package/docs/API/60-playwright/10-construction/index.md

@@ -0,0 +1,3 @@
+## Construction
+
+Fabriques de sites, pages, composants, interactions et wrappers de parcours.

package/docs/API/60-playwright/20-actions/10-check.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.check
+ *
+ * Cocher un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.check(searchForm, "onlyPublished");

package/docs/API/60-playwright/20-actions/10-clear.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.clear
+ *
+ * Effacer un champ visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.clear(searchForm, "query");

package/docs/API/60-playwright/20-actions/10-click.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.click
+ *
+ * Cliquer sur un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.click(searchForm, "submit");

package/docs/API/60-playwright/20-actions/10-dragTo.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Actions.dragTo
+ *
+ * Glisser un élément visible vers une cible visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { board } from "../fixtures/component";
+
+// La source et la cible doivent être visibles avant le glisser-déposer.
+await Actions.dragTo(board, "task", board.elements.doneColumn, { timeout: 5000 });

package/docs/API/60-playwright/20-actions/10-extractContent.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Actions.extractContent
+ *
+ * Extraire le contenu textuel d’un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { articleList } from "../fixtures/component";
+
+// Le résultat runtime est le texte du titre, ou null si son contenu textuel est absent.
+const title = await Actions.extractContent(articleList, "title");

package/docs/API/60-playwright/20-actions/10-fill.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.fill
+ *
+ * Remplacer la valeur d’un champ visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.fill(searchForm, "query", "TypeScript");

package/docs/API/60-playwright/20-actions/10-focus.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.focus
+ *
+ * Donner le focus à un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.focus(searchForm, "query");

package/docs/API/60-playwright/20-actions/10-forceClick.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Actions.forceClick
+ *
+ * Forcer le clic sans contrôle préalable de visibilité.
+ */
+import { Actions } from "@duplojs/playwright";
+import { navigation } from "../fixtures/component";
+
+// Force le clic Playwright ; aucun contrôle préalable de visibilité n’est effectué.
+await Actions.forceClick(navigation, "menuButton");

package/docs/API/60-playwright/20-actions/10-hover.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.hover
+ *
+ * Survoler un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { navigation } from "../fixtures/component";
+
+await Actions.hover(navigation, "menuButton");

package/docs/API/60-playwright/20-actions/10-press.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.press
+ *
+ * Appuyer sur une touche dans un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.press(searchForm, "query", "Enter");

package/docs/API/60-playwright/20-actions/10-selectOption.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Actions.selectOption
+ *
+ * Sélectionner des options et retourner leurs valeurs.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+// Le select autorise plusieurs valeurs ; au runtime, le résultat contient les valeurs sélectionnées.
+const selected = await Actions.selectOption(searchForm, "categories", ["typescript", "testing"]);

package/docs/API/60-playwright/20-actions/10-type.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Actions.type
+ *
+ * Saisir le texte caractère par caractère dans un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+// Contrairement à fill, la saisie déclenche une séquence de touches pour chaque caractère.
+await Actions.type(searchForm, "query", "Ada", { delay: 20 });

package/docs/API/60-playwright/20-actions/10-uncheck.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.uncheck
+ *
+ * Décocher un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.uncheck(searchForm, "onlyPublished");

package/docs/API/60-playwright/20-actions/10-withStep.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Actions.withStep
+ *
+ * Ajouter une étape Playwright nommée autour d’une interaction.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+// Cette étape englobe celle produite par click dans le rapport Playwright.
+await Actions.withStep("Lancer la recherche").click(searchForm, "submit");

package/docs/API/60-playwright/20-actions/index.llms.md

@@ -0,0 +1,60 @@
+## Actions
+
+Interactions avec les éléments nommés des pages et composants.
+
+### [Actions.check](10-check.ts)
+
+Cocher un élément visible.
+ 
+### [Actions.clear](10-clear.ts)
+
+Effacer un champ visible.
+ 
+### [Actions.click](10-click.ts)
+
+Cliquer sur un élément visible.
+ 
+### [Actions.dragTo](10-dragTo.ts)
+
+Glisser un élément visible vers une cible visible.
+ 
+### [Actions.extractContent](10-extractContent.ts)
+
+Extraire le contenu textuel d’un élément visible.
+ 
+### [Actions.fill](10-fill.ts)
+
+Remplacer la valeur d’un champ visible.
+ 
+### [Actions.focus](10-focus.ts)
+
+Donner le focus à un élément visible.
+ 
+### [Actions.forceClick](10-forceClick.ts)
+
+Forcer le clic sans contrôle préalable de visibilité.
+ 
+### [Actions.hover](10-hover.ts)
+
+Survoler un élément visible.
+ 
+### [Actions.press](10-press.ts)
+
+Appuyer sur une touche dans un élément visible.
+ 
+### [Actions.selectOption](10-selectOption.ts)
+
+Sélectionner des options et retourner leurs valeurs.
+ 
+### [Actions.type](10-type.ts)
+
+Saisir le texte caractère par caractère dans un élément visible.
+ 
+### [Actions.uncheck](10-uncheck.ts)
+
+Décocher un élément visible.
+ 
+### [Actions.withStep](10-withStep.ts)
+
+Ajouter une étape Playwright nommée autour d’une interaction.
+ 

package/docs/API/60-playwright/20-actions/index.md

@@ -0,0 +1,3 @@
+## Actions
+
+Interactions avec les éléments nommés des pages et composants.

package/docs/API/60-playwright/30-assertions/10-toBeBusy.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Assertions.toBeBusy
+ *
+ * Vérifier aria-busy="true" sur un élément visible.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { articleList } from "../fixtures/component";
+
+// Exige aria-busy="true" sur cet élément visible.
+await Assertions.toBeBusy(articleList, "loading");

package/docs/API/60-playwright/30-assertions/10-toBeChecked.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Assertions.toBeChecked
+ *
+ * Vérifier qu’un élément visible est coché.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Assertions.toBeChecked(searchForm, "onlyPublished");

package/docs/API/60-playwright/30-assertions/10-toBeDisabled.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Assertions.toBeDisabled
+ *
+ * Vérifier qu’un élément visible est désactivé.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Assertions.toBeDisabled(searchForm, "submit");

package/docs/API/60-playwright/30-assertions/10-toBeEnabled.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Assertions.toBeEnabled
+ *
+ * Vérifier qu’un élément visible est activé.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Assertions.toBeEnabled(searchForm, "submit");

package/docs/API/60-playwright/30-assertions/10-toBeHidden.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Assertions.toBeHidden
+ *
+ * Vérifier que l’élément est caché.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { navigation } from "../fixtures/component";
+
+await Assertions.toBeHidden(navigation, "menu");

package/docs/API/60-playwright/30-assertions/10-toBeNotBusy.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Assertions.toBeNotBusy
+ *
+ * Vérifier aria-busy="false" sur un élément visible.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { articleList } from "../fixtures/component";
+
+// Exige aria-busy="false", et non simplement l’absence de l’attribut.
+await Assertions.toBeNotBusy(articleList, "loading");

package/docs/API/60-playwright/30-assertions/10-toBeVisible.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Assertions.toBeVisible
+ *
+ * Faire défiler jusqu’à l’élément puis vérifier sa visibilité.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { navigation } from "../fixtures/component";
+
+// L’élément est d’abord défilé dans la vue, puis sa visibilité est vérifiée.
+await Assertions.toBeVisible(navigation, "menu");

package/docs/API/60-playwright/30-assertions/10-toContainText.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Assertions.toContainText
+ *
+ * Vérifier une partie du texte d’un élément visible.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { articleList } from "../fixtures/component";
+
+await Assertions.toContainText(articleList, "title", /TypeScript/);

package/docs/API/60-playwright/30-assertions/10-toHaveAttribute.ts

@@ -0,0 +1,12 @@
+/**
+ * @title Assertions.toHaveAttribute
+ *
+ * Vérifier un attribut d’un élément visible.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { navigation } from "../fixtures/component";
+
+await Assertions.toHaveAttribute(navigation, "menuButton", "aria-expanded", "true");
+
+// Sans valeur, l’attribut doit correspondre à /.+/ : une valeur vide ne suffit pas.
+await Assertions.toHaveAttribute(navigation, "menuButton", "aria-controls");

package/docs/API/60-playwright/30-assertions/10-toHaveClass.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Assertions.toHaveClass
+ *
+ * Vérifier les classes d’un élément visible.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { navigation } from "../fixtures/component";
+
+await Assertions.toHaveClass(navigation, "menuButton", /active/);

package/docs/API/60-playwright/30-assertions/10-toHaveNoText.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Assertions.toHaveNoText
+ *
+ * Vérifier que le texte d’un élément visible est vide.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+// Le message visible doit avoir un texte vide.
+await Assertions.toHaveNoText(searchForm, "feedback");

package/docs/API/60-playwright/30-assertions/10-toHaveQuantity.ts

@@ -0,0 +1,20 @@
+/**
+ * @title Assertions.toHaveQuantity
+ *
+ * Vérifier le nombre d’éléments correspondants.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { articleList } from "../fixtures/component";
+
+// Sans opérateur, ou avec "e", le nombre doit être exact.
+await Assertions.toHaveQuantity(articleList, "articles", { quantity: 2 });
+
+// Les bornes sont inclusives ; le comptage est réessayé pendant 5 secondes au plus.
+await Assertions.toHaveQuantity(articleList, "articles", {
+	quantity: 1,
+	operator: "gte",
+});
+await Assertions.toHaveQuantity(articleList, "articles", {
+	quantity: 3,
+	operator: "lte",
+});

package/docs/API/60-playwright/30-assertions/10-toHaveText.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Assertions.toHaveText
+ *
+ * Vérifier le texte complet d’un élément visible.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { articleList } from "../fixtures/component";
+
+await Assertions.toHaveText(articleList, "title", "Introduction à TypeScript");

package/docs/API/60-playwright/30-assertions/10-toHaveValue.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Assertions.toHaveValue
+ *
+ * Vérifier la valeur d’un élément visible.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Assertions.toHaveValue(searchForm, "query", "TypeScript");

package/docs/API/60-playwright/30-assertions/10-withStep.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Assertions.withStep
+ *
+ * Ajouter une étape Playwright nommée autour d’une interaction.
+ */
+import { Assertions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+// Cette étape englobe celle produite par l’assertion dans le rapport Playwright.
+await Assertions.withStep("Vérifier la recherche").toBeEnabled(searchForm, "submit");

package/docs/API/60-playwright/30-assertions/index.llms.md

@@ -0,0 +1,64 @@
+## Assertions
+
+Vérifications de l’état des éléments nommés des pages et composants.
+
+### [Assertions.toBeBusy](10-toBeBusy.ts)
+
+Vérifier aria-busy="true" sur un élément visible.
+ 
+### [Assertions.toBeChecked](10-toBeChecked.ts)
+
+Vérifier qu’un élément visible est coché.
+ 
+### [Assertions.toBeDisabled](10-toBeDisabled.ts)
+
+Vérifier qu’un élément visible est désactivé.
+ 
+### [Assertions.toBeEnabled](10-toBeEnabled.ts)
+
+Vérifier qu’un élément visible est activé.
+ 
+### [Assertions.toBeHidden](10-toBeHidden.ts)
+
+Vérifier que l’élément est caché.
+ 
+### [Assertions.toBeNotBusy](10-toBeNotBusy.ts)
+
+Vérifier aria-busy="false" sur un élément visible.
+ 
+### [Assertions.toBeVisible](10-toBeVisible.ts)
+
+Faire défiler jusqu’à l’élément puis vérifier sa visibilité.
+ 
+### [Assertions.toContainText](10-toContainText.ts)
+
+Vérifier une partie du texte d’un élément visible.
+ 
+### [Assertions.toHaveAttribute](10-toHaveAttribute.ts)
+
+Vérifier un attribut d’un élément visible.
+ 
+### [Assertions.toHaveClass](10-toHaveClass.ts)
+
+Vérifier les classes d’un élément visible.
+ 
+### [Assertions.toHaveNoText](10-toHaveNoText.ts)
+
+Vérifier que le texte d’un élément visible est vide.
+ 
+### [Assertions.toHaveQuantity](10-toHaveQuantity.ts)
+
+Vérifier le nombre d’éléments correspondants.
+ 
+### [Assertions.toHaveText](10-toHaveText.ts)
+
+Vérifier le texte complet d’un élément visible.
+ 
+### [Assertions.toHaveValue](10-toHaveValue.ts)
+
+Vérifier la valeur d’un élément visible.
+ 
+### [Assertions.withStep](10-withStep.ts)
+
+Ajouter une étape Playwright nommée autour d’une interaction.
+ 

package/docs/API/60-playwright/30-assertions/index.md

@@ -0,0 +1,3 @@
+## Assertions
+
+Vérifications de l’état des éléments nommés des pages et composants.

package/docs/API/60-playwright/fixtures/component.ts

@@ -0,0 +1,44 @@
+import { createComponent, type Website } from "@duplojs/playwright";
+
+declare const website: Website;
+
+const searchFormEngine = createComponent("search form", {
+	getMainElement: ({ body }) => body.locator("form[data-search]"),
+	getElements: ({ mainElement }) => ({
+		query: mainElement.locator("input[name='query']"),
+		submit: mainElement.locator("button[type='submit']"),
+		onlyPublished: mainElement.locator("input[name='published']"),
+		categories: mainElement.locator("select[name='categories'][multiple]"),
+		feedback: mainElement.locator("[role='status']"),
+	}),
+});
+
+const articleListEngine = createComponent("article list", {
+	getMainElement: ({ body }) => body.locator("[data-article-list]"),
+	getElements: ({ mainElement }) => ({
+		articles: mainElement.locator("article"),
+		title: mainElement.locator("h2").first(),
+		loading: mainElement.locator("[data-loading]"),
+	}),
+});
+
+const navigationEngine = createComponent("navigation", {
+	getMainElement: ({ body }) => body.locator("nav"),
+	getElements: ({ mainElement }) => ({
+		menuButton: mainElement.locator("button[data-menu]"),
+		menu: mainElement.locator("[data-menu-items]"),
+	}),
+});
+
+const boardEngine = createComponent("kanban board", {
+	getMainElement: ({ body }) => body.locator("[data-board]"),
+	getElements: ({ mainElement }) => ({
+		task: mainElement.locator("[data-task='review']"),
+		doneColumn: mainElement.locator("[data-column='done']"),
+	}),
+});
+
+export const searchForm = searchFormEngine(website);
+export const articleList = articleListEngine(website);
+export const navigation = navigationEngine(website);
+export const board = boardEngine(website);

package/docs/API/60-playwright/index.md

@@ -0,0 +1,3 @@
+# @duplojs/playwright
+
+Fabriques de site, pages et composants, interactions et assertions pour les parcours E2E.

package/docs/API/index.md

@@ -0,0 +1,3 @@
+# Référence API
+
+Références des fonctions publiques de l’écosystème DuploJS, organisées par package, namespace et domaine.