playwright-checkpoint 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -1358,6 +1358,12 @@ function createManifest(sessionMetadata) {
     checkpoints: []
   };
 }
+function resolveTestConfig(testConfig) {
+  if (typeof testConfig === "function") {
+    return testConfig();
+  }
+  return testConfig ?? null;
+}
 async function writeManifestFile(manifestPath, manifest) {
   await import_promises12.default.mkdir(import_node_path13.default.dirname(manifestPath), { recursive: true });
   await import_promises12.default.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}
@@ -1563,7 +1569,7 @@ async function createCheckpointSession(page, options) {
     }
   }
   await import_promises12.default.mkdir(outputDir, { recursive: true });
-  await ensureCollectorsSetup(resolveCollectors(sessionConfig));
+  await ensureCollectorsSetup(resolveCollectors(sessionConfig, resolveTestConfig(options.testConfig)));
   return {
     outputDir,
     manifest,
@@ -1571,7 +1577,7 @@ async function createCheckpointSession(page, options) {
       if (finalizePromise) {
         throw new Error("Checkpoint session has already been finalized.");
       }
-      const resolvedCollectors = resolveCollectors(sessionConfig, null, checkpointOptions);
+      const resolvedCollectors = resolveCollectors(sessionConfig, resolveTestConfig(options.testConfig), checkpointOptions);
       await ensureCollectorsSetup(resolvedCollectors);
       return runCollectorPipeline({
         page,
@@ -1648,11 +1654,54 @@ function mergeCollectorOverrides(current, updates) {
 }
 function mergeTestConfig(current, update) {
   const collectors = mergeCollectorOverrides(current?.collectors, update.collectors);
+  const article = mergeArticleMetadata(current?.article, update.article);
+  const articles = update.articles ? cloneArticleDefinitions(update.articles) : current?.articles ? cloneArticleDefinitions(current.articles) : void 0;
   return {
     description: update.description ?? current?.description,
+    ...article ? { article } : {},
+    ...articles ? { articles } : {},
     ...collectors ? { collectors } : {}
   };
 }
+function mergeArticleMetadata(current, update) {
+  if (!current && !update) {
+    return void 0;
+  }
+  const merged = {
+    ...current ?? {},
+    ...update ?? {}
+  };
+  if (current?.frontmatter || update?.frontmatter) {
+    merged.frontmatter = {
+      ...current?.frontmatter ?? {},
+      ...update?.frontmatter ?? {}
+    };
+  }
+  return merged;
+}
+function cloneArticleMetadata(article) {
+  return {
+    ...article,
+    ...article.frontmatter ? { frontmatter: { ...article.frontmatter } } : {}
+  };
+}
+function cloneArticleDefinition(article) {
+  return {
+    ...cloneArticleMetadata(article),
+    steps: [...article.steps]
+  };
+}
+function cloneArticleDefinitions(articles) {
+  return articles.map((article) => cloneArticleDefinition(article));
+}
+function syncManifestArticle(manifest, testConfig) {
+  if (testConfig?.article) {
+    manifest.article = cloneArticleMetadata(testConfig.article);
+  }
+  if (testConfig?.articles) {
+    manifest.articles = cloneArticleDefinitions(testConfig.articles);
+  }
+}
 function manifestEnvironment() {
   return process.env.PLAYWRIGHT_CHECKPOINT_ENV || process.env.NODE_ENV || "test";
 }
@@ -1729,6 +1778,8 @@ function createCheckpoint(globalConfig = {}) {
   const base = playwright.test;
   const test2 = base.extend({
     checkpointManifest: [
+      // Playwright fixture callbacks must use object destructuring for the first arg.
+      // eslint-disable-next-line no-empty-pattern
       async ({}, use, testInfo) => {
         const manifest = createCheckpointManifestRecord(testInfo);
         try {
@@ -1743,6 +1794,8 @@ function createCheckpoint(globalConfig = {}) {
       },
       { auto: true }
     ],
+    // Playwright fixture callbacks must use object destructuring for the first arg.
+    // eslint-disable-next-line no-empty-pattern
     testCheckpointConfig: async ({}, use) => {
       let current = null;
       const controller = {
@@ -1758,6 +1811,8 @@ function createCheckpoint(globalConfig = {}) {
       };
       await use(controller);
     },
+    // Playwright fixture callbacks must use object destructuring for the first arg.
+    // eslint-disable-next-line no-empty-pattern
     deviceProfile: async ({}, use, testInfo) => {
       await use(createDeviceProfile(testInfo));
     },
@@ -1766,15 +1821,20 @@ function createCheckpoint(globalConfig = {}) {
         outputDir: testInfo.outputPath("checkpoints"),
         manifestPath: testInfo.outputPath("checkpoint-manifest.json"),
         manifest: checkpointManifest,
-        collectors: mergeConfig(globalConfig, testCheckpointConfig.get()),
+        collectors: globalConfig.collectors,
+        testConfig: () => testCheckpointConfig.get(),
         custom: globalConfig.custom,
         redact: globalConfig.redact,
         testInfo,
         adjustTimeout: createAdjustTimeout(testInfo)
       });
       try {
-        await use((name, options = {}) => session.checkpoint(name, options));
+        await use((name, options = {}) => {
+          syncManifestArticle(checkpointManifest, testCheckpointConfig.get());
+          return session.checkpoint(name, options);
+        });
       } finally {
+        syncManifestArticle(checkpointManifest, testCheckpointConfig.get());
         await session.finalize();
       }
     }
@@ -2425,6 +2485,28 @@ function stripTags(value) {
   const stripped = value.replace(/\s+@[a-z0-9-]+/gi, " ").replace(/\s+/g, " ").trim();
   return stripped || value.trim() || "Untitled story";
 }
+function articleTitle(run) {
+  const override = run.article?.title?.trim();
+  return override || stripTags(run.title);
+}
+function articleDescription(run) {
+  const description = run.article?.description?.trim();
+  return description ? description : null;
+}
+function articleSlug(run) {
+  const override = run.article?.slug?.trim();
+  return slugify2(override || stripTags(run.title));
+}
+function uniqueArticleSlug(baseSlug, usedSlugs) {
+  if (!usedSlugs.has(baseSlug)) {
+    return baseSlug;
+  }
+  let index = 1;
+  while (usedSlugs.has(`${baseSlug}-${index}`)) {
+    index += 1;
+  }
+  return `${baseSlug}-${index}`;
+}
 function normalizeConfig(config) {
   return {
     storiesDir: typeof config.storiesDir === "string" ? config.storiesDir : ".",
@@ -2435,7 +2517,8 @@ function normalizeConfig(config) {
     footer: typeof config.footer === "string" ? config.footer : void 0,
     frontmatter: config.frontmatter === true || config.frontmatter === false || config.frontmatter != null && typeof config.frontmatter === "object" && !Array.isArray(config.frontmatter) ? config.frontmatter : false,
     imagePathPrefix: typeof config.imagePathPrefix === "string" ? config.imagePathPrefix : void 0,
-    copyScreenshots: typeof config.copyScreenshots === "boolean" ? config.copyScreenshots : true
+    copyScreenshots: typeof config.copyScreenshots === "boolean" ? config.copyScreenshots : true,
+    requireExplicitStep: typeof config.requireExplicitStep === "boolean" ? config.requireExplicitStep : false
   };
 }
 function normalizeTags(tags) {
@@ -2447,6 +2530,9 @@ function shouldIncludeRun(run, config) {
     const runTags = new Set(normalizeTags(run.tags));
     return includeTags.some((tag) => runTags.has(tag));
   }
+  if (run.articles) {
+    return true;
+  }
   return run.checkpoints.some((checkpoint) => {
     const hasDescription = typeof checkpoint.description === "string" && checkpoint.description.trim().length > 0;
     return hasDescription || typeof checkpoint.step === "number";
@@ -2565,17 +2651,22 @@ async function materializeScreenshot(args) {
   if (!sourcePath) {
     return null;
   }
+  const cachedTargetPath = args.screenshotCopies?.get(sourcePath);
+  if (cachedTargetPath) {
+    return rewriteImagePath(args.markdownFile, cachedTargetPath, args.outputDir, args.config.imagePathPrefix);
+  }
   const extension = import_node_path16.default.extname(sourcePath) || ".png";
   const targetPath = import_node_path16.default.join(
     args.outputDir,
     args.config.screenshotsDir ?? "screenshots",
-    args.storySlug,
-    `${String(args.stepOrder).padStart(2, "0")}-${slugify2(args.checkpoint.name)}${extension}`
+    args.screenshotDirSlug,
+    `${args.screenshotFileSlug}${extension}`
   );
   try {
     if (args.config.copyScreenshots !== false) {
       await import_promises15.default.mkdir(import_node_path16.default.dirname(targetPath), { recursive: true });
       await import_promises15.default.copyFile(sourcePath, targetPath);
+      args.screenshotCopies?.set(sourcePath, targetPath);
       args.writtenFiles.add(targetPath);
       return rewriteImagePath(args.markdownFile, targetPath, args.outputDir, args.config.imagePathPrefix);
     }
@@ -2595,10 +2686,31 @@ function orderedCheckpoints(checkpoints) {
   });
 }
 async function buildSteps(args) {
-  const checkpoints = orderedCheckpoints(args.run.checkpoints);
+  let checkpoints;
+  if (args.stepNames && args.stepNames.length > 0) {
+    const byName = /* @__PURE__ */ new Map();
+    for (const checkpoint of args.run.checkpoints) {
+      if (byName.has(checkpoint.name)) {
+        warn(`Duplicate checkpoint name "${checkpoint.name}" in "${args.run.title}". Using the latest capture for article generation.`);
+      }
+      byName.set(checkpoint.name, checkpoint);
+    }
+    checkpoints = args.stepNames.map((stepName) => {
+      const checkpoint = byName.get(stepName);
+      if (!checkpoint) {
+        warn(`Markdown article step "${stepName}" was not captured in "${args.run.title}". Skipping step.`);
+        return null;
+      }
+      return checkpoint;
+    }).filter((checkpoint) => checkpoint !== null);
+  } else {
+    checkpoints = orderedCheckpoints(args.run.checkpoints).filter(
+      (checkpoint) => !args.config.requireExplicitStep || typeof checkpoint.step === "number"
+    );
+  }
   const steps = [];
   for (const [index, checkpoint] of checkpoints.entries()) {
-    const order = typeof checkpoint.step === "number" ? checkpoint.step : index + 1;
+    const order = args.stepNames ? index + 1 : typeof checkpoint.step === "number" ? checkpoint.step : index + 1;
     steps.push({
       checkpoint,
       order,
@@ -2607,12 +2719,13 @@ async function buildSteps(args) {
       imagePath: await materializeScreenshot({
         run: args.run,
         checkpoint,
-        storySlug: args.storySlug,
-        stepOrder: order,
+        screenshotDirSlug: args.screenshotDirSlug,
+        screenshotFileSlug: args.stepNames ? checkpoint.slug : `${String(order).padStart(2, "0")}-${slugify2(checkpoint.name)}`,
         outputDir: args.outputDir,
         markdownFile: args.markdownFile,
         config: args.config,
-        writtenFiles: args.writtenFiles
+        writtenFiles: args.writtenFiles,
+        screenshotCopies: args.screenshotCopies
       }),
       urlLabel: urlLabel(checkpoint.url),
       breadcrumbLabel: breadcrumbLabel(checkpoint.url),
@@ -2623,13 +2736,14 @@ async function buildSteps(args) {
 }
 function renderMarkdown(args) {
   const frontmatterFields = args.config.frontmatter === true || typeof args.config.frontmatter === "object" ? {
-    title: args.title,
     project: args.run.project,
-    testId: args.run.testId,
     tags: args.run.tags,
+    ...args.config.frontmatter && typeof args.config.frontmatter === "object" ? args.config.frontmatter : {},
+    ...args.article?.frontmatter ?? {},
+    testId: args.run.testId,
     startedAt: args.run.startedAt,
     generatedAt: args.generatedAt,
-    ...args.config.frontmatter && typeof args.config.frontmatter === "object" ? args.config.frontmatter : {}
+    title: args.title
   } : null;
   const sections = args.steps.map((step) => {
     const lines = [`## Step ${step.order}: ${step.heading}`, ""];
@@ -2649,6 +2763,7 @@ function renderMarkdown(args) {
   const parts = [
     frontmatterFields ? serializeFrontmatter(frontmatterFields) : "",
     `# ${args.title}`,
+    args.description?.trim() ?? "",
     args.config.header ? args.config.header.trim() : "",
     sections,
     args.config.footer ? args.config.footer.trim() : ""
@@ -2656,6 +2771,42 @@ function renderMarkdown(args) {
   return `${parts.join("\n\n")}
 `;
 }
+function resolveArticles(run) {
+  const multiArticles = (run.articles ?? []).filter((article) => Array.isArray(article.steps));
+  if (run.articles && multiArticles.length === 0) {
+    warn(`Markdown reporter received an empty articles array for "${run.title}". Falling back to the default single-article output.`);
+  }
+  if (multiArticles.length === 0) {
+    return [
+      {
+        title: articleTitle(run),
+        description: articleDescription(run),
+        slug: articleSlug(run),
+        metadata: run.article,
+        screenshotDirSlug: articleSlug(run)
+      }
+    ];
+  }
+  const usedSlugs = /* @__PURE__ */ new Set();
+  const screenshotDirSlug = slugify2(stripTags(run.title));
+  return multiArticles.map((article, index) => {
+    const fallbackSlug = `${screenshotDirSlug}-${index + 1}`;
+    const baseSlug = slugify2(article.slug?.trim() || fallbackSlug);
+    const uniqueSlug = uniqueArticleSlug(baseSlug, usedSlugs);
+    if (uniqueSlug !== baseSlug) {
+      warn(`Markdown article slug collision for "${article.title ?? run.title}" resolved as "${uniqueSlug}".`);
+    }
+    usedSlugs.add(uniqueSlug);
+    return {
+      title: article.title?.trim() || stripTags(run.title),
+      description: article.description?.trim() || null,
+      slug: uniqueSlug,
+      metadata: article,
+      stepNames: [...article.steps],
+      screenshotDirSlug
+    };
+  });
+}
 var markdownReporter = {
   name: "markdown",
   description: "Generates one Markdown help article per captured story.",
@@ -2667,37 +2818,56 @@ var markdownReporter = {
     const stories = groupByStory(context.runs);
     const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
     const writtenFiles = /* @__PURE__ */ new Set();
+    const usedStorySlugs = /* @__PURE__ */ new Set();
+    const screenshotCopies = /* @__PURE__ */ new Map();
     let articleCount = 0;
     for (const [storyTitle, runs] of stories) {
       const primaryRun = choosePrimaryRun(runs, config.preferredProject);
       if (!primaryRun || !shouldIncludeRun(primaryRun, config)) {
         continue;
       }
-      const title = stripTags(storyTitle);
-      const storySlug = slugify2(title);
-      const markdownFile = import_node_path16.default.join(context.outputDir, config.storiesDir ?? ".", `${storySlug}.md`);
-      const steps = await buildSteps({
-        run: primaryRun,
-        storySlug,
-        outputDir: context.outputDir,
-        markdownFile,
-        config,
-        writtenFiles
-      });
-      await import_promises15.default.mkdir(import_node_path16.default.dirname(markdownFile), { recursive: true });
-      await import_promises15.default.writeFile(
-        markdownFile,
-        renderMarkdown({
-          title,
-          steps,
+      for (const article of resolveArticles(primaryRun)) {
+        let storySlug = article.slug;
+        if (usedStorySlugs.has(storySlug)) {
+          let index = 2;
+          while (usedStorySlugs.has(`${article.slug}-${index}`)) {
+            index += 1;
+          }
+          storySlug = `${article.slug}-${index}`;
+          warn(`Markdown article slug collision for "${article.title || storyTitle}" resolved as "${storySlug}".`);
+        }
+        usedStorySlugs.add(storySlug);
+        const markdownFile = import_node_path16.default.join(context.outputDir, config.storiesDir ?? ".", `${storySlug}.md`);
+        const steps = await buildSteps({
           run: primaryRun,
+          stepNames: article.stepNames,
+          screenshotDirSlug: article.screenshotDirSlug,
+          outputDir: context.outputDir,
+          markdownFile,
           config,
-          generatedAt
-        }),
-        "utf8"
-      );
-      writtenFiles.add(markdownFile);
-      articleCount += 1;
+          writtenFiles,
+          screenshotCopies
+        });
+        if (steps.length === 0) {
+          continue;
+        }
+        await import_promises15.default.mkdir(import_node_path16.default.dirname(markdownFile), { recursive: true });
+        await import_promises15.default.writeFile(
+          markdownFile,
+          renderMarkdown({
+            title: article.title,
+            description: article.description,
+            steps,
+            run: primaryRun,
+            article: article.metadata,
+            config,
+            generatedAt
+          }),
+          "utf8"
+        );
+        writtenFiles.add(markdownFile);
+        articleCount += 1;
+      }
     }
     return {
       files: [...writtenFiles],
@@ -3163,6 +3333,8 @@ function toRunRecord(manifest, sourceManifestPath) {
     project: manifest.project,
     testId: manifest.testId,
     title: manifest.title,
+    ...manifest.article ? { article: manifest.article } : {},
+    ...manifest.articles ? { articles: manifest.articles } : {},
     tags: manifest.tags,
     startedAt: manifest.startedAt,
     checkpoints: manifest.checkpoints
@@ -3174,6 +3346,8 @@ function toManifest(run) {
     project: run.project,
     testId: run.testId,
     title: run.title,
+    ...run.article ? { article: run.article } : {},
+    ...run.articles ? { articles: run.articles } : {},
     tags: run.tags,
     startedAt: run.startedAt,
     checkpoints: run.checkpoints