@poveste/plugin-screenshot 0.10.0 → 0.12.0

package/README.md

@@ -19,6 +19,30 @@ export default defineConfig({
 })
 ```
 
+## Where the screenshots go
+
+By default the plugin writes one PNG per variant per responsive preset into `.poveste/screenshots`, inside your project:
+
+```
+.poveste/screenshots/<story-id>-<variant-id>-<width>x<height>.png
+```
+
+**Add that folder to your `.gitignore`.** It is build output, it is regenerated on every run, and one binary per variant adds up quickly — a book of any size will otherwise fill a commit the first time somebody runs `git add -A`.
+
+```gitignore
+.poveste/
+```
+
+Ignoring the whole `.poveste/` directory covers the built book as well. Set `saveFolder` if you would rather keep the screenshots somewhere else — a path you compare baselines from, for instance:
+
+```js
+HstScreenshot({
+  saveFolder: 'tests/screenshots',
+})
+```
+
+That folder is yours to decide about: baselines you intend to commit belong in tracked storage, and the default does not.
+
 ## Setting Up Chrome Linux Sandbox
 
 If you get `No usable sandbox!` or `Running as root without --no-sandbox is not

package/dist/index.d.ts

@@ -36,5 +36,14 @@ export interface ScreenshotPluginOptions {
      */
     launchOptionsArgs?: string[];
 }
+/**
+ * The file one capture is written to.
+ *
+ * A variant with no explicit `id` is given `${story.id}-${n}`, so naming the
+ * file `${story.id}-${variant.id}` repeated the story id in full. The story id
+ * still has to be there for the named case: `default` and `one` are only unique
+ * within their own story.
+ */
+export declare function screenshotFileName(storyId: string, variantId: string, width: number, height: number): string;
 export declare function HstScreenshot(options?: ScreenshotPluginOptions): Plugin;
 export {};

package/dist/index.js

@@ -5,6 +5,19 @@ const defaultOptions = {
     saveFolder: '.poveste/screenshots',
     presets: [],
 };
+/**
+ * The file one capture is written to.
+ *
+ * A variant with no explicit `id` is given `${story.id}-${n}`, so naming the
+ * file `${story.id}-${variant.id}` repeated the story id in full. The story id
+ * still has to be there for the named case: `default` and `one` are only unique
+ * within their own story.
+ */
+export function screenshotFileName(storyId, variantId, width, height) {
+    const prefix = `${storyId}-`;
+    const variant = variantId.startsWith(prefix) ? variantId.slice(prefix.length) : variantId;
+    return `${storyId}-${variant}-${width}x${height}.png`;
+}
 export function HstScreenshot(options = {}) {
     const finalOptions = defu(options, defaultOptions);
     if (!finalOptions.presets.length) {
@@ -45,7 +58,7 @@ export function HstScreenshot(options = {}) {
                         fullPage: true,
                         launchOptions,
                     };
-                    await captureWebsite.file(url, path.join(finalOptions.saveFolder, `${story.id}-${variant.id}-${preset.width}x${preset.height}.png`), captureWebsiteFileOptions);
+                    await captureWebsite.file(url, path.join(finalOptions.saveFolder, screenshotFileName(story.id, variant.id, preset.width, preset.height)), captureWebsiteFileOptions);
                 }
             });
         },

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@poveste/plugin-screenshot",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Poveste plugin to take screenshots for visual regression testing",
   "author": {
-    "name": "Sorin Gitlan"
+    "name": "Sorin Gitlan",
+    "url": "https://x.com/50rayn"
   },
   "license": "MIT",
   "homepage": "https://poveste.dev",
@@ -46,7 +47,7 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "peerDependencies": {
-    "poveste": "^0.10.0"
+    "poveste": "^0.12.0"
   },
   "dependencies": {
     "capture-website": "^4.2.0",
@@ -56,11 +57,14 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.1",
+    "poveste": "0.12.0",
     "typescript": "5.6.3",
-    "poveste": "0.10.0"
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "build": "rimraf dist && tsc -d",
-    "watch": "tsc -d -w --sourceMap"
+    "watch": "tsc -d -w --sourceMap",
+    "test": "vitest run",
+    "test:dev": "vitest"
   }
 }