Merge pull request #172 from argos-ci/improve-viewports

fix(storybook): improve storybook viewports doc

Author: gregberge

docs/guides/storybook-story-modes.mdx

@@ -25,7 +25,7 @@ A mode is a preset that configures various Storybook globals. For instance, you
 
 ## Setting up globals & addons
 
-Before you define any modes, make sure you’ve configured the relevant Storybook addons in your .storybook/preview.js (or .storybook/preview.ts) file. Examples include:
+Before you define any modes, make sure you’ve configured the relevant Storybook addons in your `.storybook/preview.ts` (or `.js`) file. Examples include:
 
 - [`@storybook/addon-viewport`](https://www.npmjs.com/package/@storybook/addon-viewport) for screen sizes
 - [`@storybook/addon-themes`](https://www.npmjs.com/package/@storybook/addon-themes) for light/dark themes
@@ -34,8 +34,7 @@ Before you define any modes, make sure you’ve configured the relevant Storyboo
 
 These addons utilize Storybook “globals” and “decorators” under the hood. Argos modes simply manipulate those globals at test time to generate multiple snapshots of the same story.
 
-```ts
-// .storybook/preview.js
+```ts title=".storybook/preview.ts"
 import { withThemeByClassName } from "@storybook/addon-themes";
 import "../src/styles.css";
 
@@ -76,11 +75,9 @@ export default preview;
 
 ## Defining modes
 
-Create a `.storybook/modes.js` (or `.ts`) file that exports an object where each key is a mode name and each value is a set of overrides for the Storybook globals. For example:
-
-```ts
-// .storybook/modes.js
+Create a `.storybook/modes.ts` (or `.js`) file that exports an object where each key is a mode name and each value is a set of overrides for the Storybook globals. For example:
 
+```ts title=".storybook/modes.ts"
 export const allModes = {
   dark: {
     backgrounds: { value: "#1A1A1A" },
@@ -106,17 +103,18 @@ Each object can include as many or as few globals as you need. If a mode doesn
 
 ## Applying modes
 
-Attach modes to any level of your Storybook: globally in `.storybook/preview.js`, at the component (default export) level, or in an individual story’s parameters. Argos merges all modes defined up the chain.
+Attach modes to any level of your Storybook: globally in `.storybook/preview.ts` (or `.js`), at the component (default export) level, or in an individual story’s parameters. Argos merges all modes defined up the chain.
 
 ### Basic usage in a story file
 
-```ts
-// src/components/ProductCard/ProductCard.stories.js
+```ts title="ProductCard.stories.ts"
+// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
+import type { Meta, StoryObj } from "@storybook/your-framework";
 
 import { ProductCard } from "./ProductCard";
 import { allModes } from "../../../.storybook/modes";
 
-export default {
+const meta = {
   title: "Components/ProductCard",
   component: ProductCard,
   parameters: {
@@ -128,18 +126,19 @@ export default {
       },
     },
   },
-};
+} satisfies Meta<typeof ProductCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
 
-// Story #1
-export const DefaultView = {
+export const DefaultView: Story = {
   args: {
     productName: "Coffee Beans",
     price: 9.99,
   },
 };
 
-// Story #2
-export const SoldOutView = {
+export const SoldOutView: Story = {
   args: {
     productName: "Coffee Beans",
     price: 9.99,
@@ -152,12 +151,11 @@ In this example, Argos will generate two snapshots for each story (DefaultView a
 
 ## Combining modes from multiple levels
 
-You can add modes in your .storybook/preview.js at the project level, then define additional modes in a story file. Argos “stacks” these modes, creating a snapshot for every combination.
+You can add modes in your `.storybook/preview.ts` (or `.js`) at the project level, then define additional modes in a story file. Argos “stacks” these modes, creating a snapshot for every combination.
 
 ### Project-level modes
 
-```ts
-// .storybook/preview.js
+```ts title=".storybook/modes.ts"
 import { allModes } from "./modes";
 
 const preview = {
@@ -175,12 +173,13 @@ export default preview;
 
 ### Component-level modes
 
-```ts
-// ProductCard.stories.js
+```ts title="ProductCard.stories.ts"
+// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
+import type { Meta, StoryObj } from "@storybook/your-framework";
 import { ProductCard } from "./ProductCard";
 import { allModes } from "../../../.storybook/modes";
 
-export default {
+const meta = {
   title: "Components/ProductCard",
   component: ProductCard,
   parameters: {
@@ -190,25 +189,28 @@ export default {
       },
     },
   },
-};
+} satisfies Meta<typeof ProductCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
 
-// Single story for brevity
-export const Basic = {
+export const Basic: Story = {
   args: {
     /* ... */
   },
 };
 ```
 
-When Argos runs, it will generate snapshots for each mode defined at the project level and the component level. So for Basic, you get “light mobile” (from `preview.js`) plus “dark widescreen” (from the component’s parameter).
+When Argos runs, it will generate snapshots for each mode defined at the project level and the component level. So for Basic, you get “light mobile” (from `preview.ts`) plus “dark widescreen” (from the component’s parameter).
 
 ## Excluding or disabling modes
 
 Sometimes you want to turn off a certain higher-level mode for a specific story. You can do this by passing a disable property:
 
-```ts
-// ProductCard.stories.js
-export const SpecialCard = {
+```ts title="ProductCard.stories.ts"
+// ...
+
+export const SpecialCard: Story = {
   args: {
     /* ... */
   },

docs/guides/viewports.mdx

@@ -5,30 +5,36 @@ title: Responsive Viewports
 
 # Configuring Responsive Viewports
 
-Master responsive testing with Argos: Easily configure viewports for Playwright, Cypress, and Puppeteer, ensuring your app looks great on any device.
+Argos lets you capture the same page at multiple breakpoints with a single test. Configure viewports once and get consistent responsive coverage across Playwright, Cypress and Puppeteer.
 
 ## Prerequisites
 
 This advanced feature integrates smoothly with [Playwright](/playwright), [Cypress](/cypress), and [Puppeteer](/puppeteer) to enhance your testing capabilities.
 
+This feature works seamlessly with [Playwright](/playwright), [Cypress](/cypress) and [Puppeteer](/puppeteer).
+
+:::note
+
+If you use Storybook, see the dedicated guide on [Storybook modes](/storybook-story-modes).
+
+:::
+
 ## Viewport Configuration
 
-Adjust the `argosScreenshot()` command in your test scripts to capture responsive screenshots. You can specify exact dimensions or use device presets to mimic real-world scenarios:
+Pass a viewports array to `argosScreenshot()` to generate screenshots for each dimension or preset you define. You can mix explicit sizes and device presets.
 
 ```js
 await argosScreenshot(..., {
   viewports: [
-    "iphone-4", // Use device preset
-    { width: 800, height: 600 }, // Specify dimensions directly
-    { preset: "ipad-2", orientation: "landscape" }, // Device preset with orientation
+    "iphone-4",
+    { width: 800, height: 600 },
+    { preset: "ipad-2", orientation: "landscape" },
   ],
 });
 ```
 
 ## Available Presets
 
-List of available device presets with their respective dimensions:
-
 | Preset        | Width (px) | Height (px) |
 | ------------- | ---------- | ----------- |
 | macbook-16    | 1536       | 960         |
@@ -52,4 +58,40 @@ List of available device presets with their respective dimensions:
 
 ## Troubleshooting and Best Practices
 
-To ensure accurate rendering, always set the viewport size with `page.setViewportSize()` before navigating to the target page, as many sites do not dynamically adapt to changes in viewport size after the page has loaded. For comprehensive testing, consider running your tests across all intended viewports to validate responsive behavior across the board.
+Many sites compute layout at load time and will not adapt cleanly if the viewport changes later. If you notice issues, you may want to run your test suite entirely for each viewport instead of changing the viewport before taking each screenshot.
+
+For example, in Playwright you can create a separate browser context for each viewport size.
+
+```ts title="playrwight.config.ts"
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  projects: [
+    {
+      name: "chromium-mobile",
+      use: {
+        ...devices["Desktop Chrome"],
+        channel: "chrome",
+      },
+    },
+    {
+      name: "chromium-mobile",
+      use: {
+        ...devices["Desktop Chrome"],
+        channel: "chrome",
+        viewport: { width: 402, height: 874 }, // iPhone 7 viewport
+      },
+    },
+  ],
+});
+```
+
+You can also run `page.setViewportSize()` before navigating to the page to ensure the layout is computed correctly.
+
+```ts
+await page.setViewportSize({
+  width: 640,
+  height: 480,
+});
+await page.goto("https://example.com");
+```