The open source visual testing plaform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
# Example of Argos + Storybook Test Runner @@ -23,7 +23,7 @@ Read [Argos documentations](https://argos-ci.com/docs) or explore [Storybook Tes ## Links -- [Quickstart with Argos + Storybook Test Runner](https://argos-ci.com/docs/quickstart/storybook-test-runner) -- [Storybook SDK Reference](https://argos-ci.com/docs/storybook) +- [Quickstart with Argos + Storybook Test Runner](https://argos-ci.com/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart) +- [Storybook SDK Reference](https://argos-ci.com/docs/sdks-reference/storybook) - [Official Argos Docs](https://argos-ci.com/docs) - [Discord](https://argos-ci.com/discord) diff --git a/examples/storybook-vitest/README.md b/examples/storybook-vitest/README.md index 8d8b3825..8d38bf1f 100644 --- a/examples/storybook-vitest/README.md +++ b/examples/storybook-vitest/README.md @@ -7,7 +7,7 @@ -The open source visual testing plaform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
# Example of Argos + Storybook Vitest @@ -23,7 +23,7 @@ Read [Argos documentations](https://argos-ci.com/docs) or explore [Storybook Tes ## Links -- [Quickstart with Argos + Storybook + Vitest](https://argos-ci.com/docs/quickstart/storybook) -- [Storybook SDK Reference](https://argos-ci.com/docs/storybook) +- [Quickstart with Argos + Storybook + Vitest](https://argos-ci.com/docs/quickstart/storybook-quickstart) +- [Storybook SDK Reference](https://argos-ci.com/docs/sdks-reference/storybook) - [Official Argos Docs](https://argos-ci.com/docs) - [Discord](https://argos-ci.com/discord) diff --git a/examples/storybook-vitest/vite.config.js b/examples/storybook-vitest/vite.config.js index f35cc040..b994ae7d 100644 --- a/examples/storybook-vitest/vite.config.js +++ b/examples/storybook-vitest/vite.config.js @@ -23,7 +23,7 @@ export default defineConfig({ }) // The plugin will capture screenshots of your stories and upload them to Argos. - // See options at: https://argos-ci.com/docs/storybook + // See options at: https://argos-ci.com/docs/sdks-reference/storybook argosVitestPlugin({ // Upload to Argos on CI only. uploadToArgos: !!process.env.CI, diff --git a/examples/travis/README.md b/examples/travis/README.md index 699ba771..31e0a163 100644 --- a/examples/travis/README.md +++ b/examples/travis/README.md @@ -7,7 +7,7 @@ -The open source visual testing plaform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
# Example of Argos running on Travis diff --git a/examples/webdriver-io/README.md b/examples/webdriver-io/README.md index a0542cb9..4789e723 100644 --- a/examples/webdriver-io/README.md +++ b/examples/webdriver-io/README.md @@ -7,7 +7,7 @@ -The open source visual testing plaform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
# Example of Argos + WebdriverIO diff --git a/packages/api-client/README.md b/packages/api-client/README.md index 5df0e8e1..403c1310 100644 --- a/packages/api-client/README.md +++ b/packages/api-client/README.md @@ -1,15 +1,49 @@ -_Argos is a visual testing solution that fits in your workflow to avoid visual regression. Takes screenshots on each commit and be notified if something changes._ +
+ 
+ The open source visual testing platform for AI-native engineering teams.
# Argos API Client -Argos API Client to interact with Argos API. +A typed client for the [Argos API](https://api.argos-ci.com/v2/), built on [openapi-fetch](https://openapi-ts.dev/openapi-fetch/). [](https://www.npmjs.com/package/@argos-ci/api-client) [](https://www.npmjs.com/package/@argos-ci/api-client) [](https://www.npmjs.com/package/@argos-ci/api-client) + +## Installation + +```sh +npm install @argos-ci/api-client +``` + +## Usage + +Create a client and call any endpoint. Requests and responses are fully typed from the Argos OpenAPI schema: + +```ts +import { createClient } from "@argos-ci/api-client"; + +const client = createClient({ + authToken: process.env.ARGOS_TOKEN, +}); + +const { data, error } = await client.GET("/project"); + +if (error) { + throw new Error(error.error); +} + +console.log(data); +``` + +## Links + +- [Official Docs](https://argos-ci.com/docs) +- [Discord](https://argos-ci.com/discord) diff --git a/packages/browser/README.md b/packages/browser/README.md index 620c05ab..9604aa29 100644 --- a/packages/browser/README.md +++ b/packages/browser/README.md @@ -7,16 +7,19 @@ -The open source visual testing plaform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
# Argos Browser -Browser utilities to stabilize visual testing. +Low-level browser utilities that stabilize the page before a screenshot is taken — waiting for fonts and images to load, hiding scrollbars and text carets, and resolving viewports. [](https://www.npmjs.com/package/@argos-ci/browser) [](https://www.npmjs.com/package/@argos-ci/browser) [](https://www.npmjs.com/package/@argos-ci/browser) +> This package is an internal building block used by the higher-level Argos SDKs (Playwright, Cypress, Puppeteer, …). You usually don't need to install it directly — pick the integration for your test framework instead. + ## Links - [Official SDK Docs](https://argos-ci.com/docs) +- [Discord](https://argos-ci.com/discord) diff --git a/packages/cli/README.md b/packages/cli/README.md index 2903669a..a9201b7e 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -7,16 +7,39 @@ -The open source visual testing plaform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
# Argos Command Line Interface -Argos CLI is used to interact with and upload screenshots to [argos-ci.com](https://argos-ci.com) via command line. +Interact with and upload screenshots to [argos-ci.com](https://argos-ci.com) from the command line. [](https://www.npmjs.com/package/@argos-ci/cli) [](https://www.npmjs.com/package/@argos-ci/cli) [](https://www.npmjs.com/package/@argos-ci/cli) +Visit the [Argos CLI documentation](https://argos-ci.com/docs/sdks-reference/argos-command-line-interface-cli) for the full command reference and more. + +## Installation + +```sh +npm install --save-dev @argos-ci/cli +``` + +## Usage + +Upload a directory of screenshots to Argos. Authenticate with your project token via the `ARGOS_TOKEN` environment variable: + +```sh +ARGOS_TOKEN="The open source visual testing plaform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
-# Argos JavaScript SDK Core +# Argos Node.js SDK -Argos Core JavaScript SDK contains interface definitions, base classes and utilities for building Argos JavaScript SDKs, like `@argos-ci/cli` or using it directly with Node.js. +Node.js SDK for visual testing with Argos. It powers the Argos CLI and the higher-level integrations (Playwright, Cypress, …), and can be used directly to upload screenshots from Node.js. [](https://www.npmjs.com/package/@argos-ci/core) [](https://www.npmjs.com/package/@argos-ci/core) [](https://www.npmjs.com/package/@argos-ci/core) +Visit the [Node.js SDK documentation](https://argos-ci.com/docs/sdks-reference/node.js-sdk) for guides, the API reference, and more. + +## Installation + +```sh +npm install @argos-ci/core +``` + +## Usage + +Upload a directory of screenshots to Argos and create a build: + +```ts +import { upload } from "@argos-ci/core"; + +const { build } = await upload({ + // Directory containing the screenshots. + root: "./screenshots", + // Globs matching the screenshots to upload. + files: ["**/*.png"], + // Defaults to the ARGOS_TOKEN environment variable. + token: process.env.ARGOS_TOKEN, +}); + +console.log(`Build created: ${build.url}`); +``` + ## Links -- [Official SDK Docs](https://argos-ci.com/docs) +- [Official SDK Docs](https://argos-ci.com/docs/sdks-reference/node.js-sdk) - [API Reference](https://js-sdk-reference.argos-ci.com) +- [Discord](https://argos-ci.com/discord) diff --git a/packages/core/package.json b/packages/core/package.json index a77e8bbe..9087bda7 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -18,7 +18,7 @@ "url": "https://github.com/argos-ci/argos-javascript.git", "directory": "packages/core" }, - "homepage": "https://argos-ci.com/docs/node-sdk", + "homepage": "https://argos-ci.com/docs/sdks-reference/node.js-sdk", "bugs": { "url": "https://github.com/argos-ci/argos-javascript/issues" }, diff --git a/packages/core/src/ci-environment/github.ts b/packages/core/src/ci-environment/github.ts index b188150c..e5b454b1 100644 --- a/packages/core/src/ci-environment/github.ts +++ b/packages/core/src/ci-environment/github.ts @@ -45,7 +45,7 @@ To resolve this, Argos requires a GITHUB_TOKEN to fetch the pull request associa GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }} -For more details, check out the documentation: Read more at https://argos-ci.com/docs/run-on-preview-deployment +For more details, check out the documentation: Read more at https://argos-ci.com/docs/learn/how-to-guides/ci-pipelines/run-on-preview-deployments If you want to disable this warning, you can set the following environment variable: diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts index 476e435b..4c539240 100644 --- a/packages/core/src/config.ts +++ b/packages/core/src/config.ts @@ -380,7 +380,7 @@ export interface Config { * Build mode to use. * - "ci": Review visual changes introduced by a feature branch and prevent regressions. * - "monitoring": Track visual changes outside the standard CI flow, either on a schedule or before a release. - * @see https://argos-ci.com/docs/build-modes + * @see https://argos-ci.com/docs/learn/platform-fundamentals/build-modes */ mode: "ci" | "monitoring" | null; diff --git a/packages/core/src/upload.ts b/packages/core/src/upload.ts index c936a7bc..92675b32 100644 --- a/packages/core/src/upload.ts +++ b/packages/core/src/upload.ts @@ -101,7 +101,7 @@ export interface UploadParameters { * Build mode to use. * - "ci": Review the visual changes introduced by a feature branch and prevent regressions. * - "monitoring": Track visual changes outside the standard CI flow, either on a schedule or before a release. - * @see https://argos-ci.com/docs/build-modes + * @see https://argos-ci.com/docs/learn/platform-fundamentals/build-modes * @default "ci" */ mode?: "ci" | "monitoring"; diff --git a/packages/cypress/README.md b/packages/cypress/README.md index 802c0782..ab819830 100644 --- a/packages/cypress/README.md +++ b/packages/cypress/README.md @@ -1,10 +1,13 @@ -_Argos is a visual testing solution that fits in your workflow to avoid visual regression. Takes screenshots on each commit and be notified if something changes._ +The open source visual testing platform for AI-native engineering teams.
# Official Argos Cypress integration @@ -12,9 +15,60 @@ _Argos is a visual testing solution that fits in your workflow to avoid visual r [](https://www.npmjs.com/package/@argos-ci/cypress) [](https://www.npmjs.com/package/@argos-ci/cypress) -Visit [argos-ci.com/docs/cypress](https://argos-ci.com/docs/cypress) for guides, API and more. +Capture stable Argos screenshots from your [Cypress](https://www.cypress.io/) tests. + +Visit the [Cypress SDK documentation](https://argos-ci.com/docs/sdks-reference/cypress) for guides, the API reference, and more. + +## Installation + +```sh +npm install --save-dev @argos-ci/cypress +``` + +## Usage + +Register the Argos task in your Cypress config: + +```ts +// cypress.config.js +const { defineConfig } = require("cypress"); +const { registerArgosTask } = require("@argos-ci/cypress/task"); + +module.exports = defineConfig({ + e2e: { + setupNodeEvents(on, config) { + registerArgosTask(on, config, { + // Upload the screenshots to Argos only on CI. + uploadToArgos: !!process.env.CI, + }); + + return config; + }, + }, +}); +``` + +Import the command in your support file: + +```ts +// cypress/support/e2e.js +import "@argos-ci/cypress/support"; +``` + +Then capture stable screenshots with `cy.argosScreenshot` in your tests: + +```ts +// cypress/e2e/example.cy.js +describe("Homepage", () => { + it("takes a screenshot", () => { + cy.visit("http://localhost:3000"); + cy.argosScreenshot("homepage"); + }); +}); +``` ## Links -- [Official SDK Docs](https://argos-ci.com/docs) +- [Official SDK Docs](https://argos-ci.com/docs/sdks-reference/cypress) +- [Quickstart](https://argos-ci.com/docs/quickstart/cypress-quickstart) - [Discord](https://argos-ci.com/discord) diff --git a/packages/cypress/docs/index.mdx b/packages/cypress/docs/index.mdx deleted file mode 100644 index 450bded6..00000000 --- a/packages/cypress/docs/index.mdx +++ /dev/null @@ -1,278 +0,0 @@ ---- -title: Cypress -slug: /cypress ---- - -# Argos Cypress SDK - -Boost your visual testing capabilities by combining Argos with your [Cypress](https://www.cypress.io/) tests. - -While Cypress inherently provides screenshot functionality, the Argos Cypress integration enhances this by: - -- Ensuring all images are fully loaded. -- Ensuring all fonts are rendered. -- Confirming the absence of any `aria-busy` (loading) elements on the page. -- Concealing scrollbars. -- Obscuring text cursors or carets. -- Providing CSS utilities to simplify content hiding. -- Gives you visility on test failures. - -## Get started - -Please refer to our [Quickstart guide](/quickstart/cypress) to get started with Argos and Cypress. - -## Set a Preview URL - -Argos displays the URL of the page when a screenshot is taken, helping you understand the screenshot’s context in the Argos UI. If you run tests locally and deploy your pull requests (PRs) to a preview URL, you can link the two by setting the `ARGOS_PREVIEW_URL` environment variable or configuring the `previewUrl` option in the Cypress configuration. - -### Example Configuration - -```ts title="cypress.config.js" -const { defineConfig } = require("cypress"); -const { registerArgosTask } = require("@argos-ci/cypress/task"); - -module.exports = defineConfig({ - e2e: { - async setupNodeEvents(on, config) { - registerArgosTask(on, config, { - uploadToArgos: !!process.env.CI, - previewUrl: { - baseUrl: "https://my-site.com", // Use a dynamic value here for different environments if needed. - }, - }); - }, - }, -}); -``` - -## Setup individual Cypress events - -Cypress only supports one handler per event. If you need to set up other handlers for the same event, you can call the individual functions provided by the SDK. - -```ts title="cypress.config.js" -const { defineConfig } = require("cypress"); -const { - argosAfterScreenshot, - argosAfterRun, -} = require("@argos-ci/cypress/task"); - -module.exports = defineConfig({ - // setupNodeEvents can be defined in either - // the e2e or component configuration - e2e: { - async setupNodeEvents(on, config) { - const argosConfig = { - uploadToArgos: !!process.env.CI, - }; - - on("after:screenshot", async (details) => { - // Your custom logic... - - return argosAfterScreenshot(config, details, argosConfig); - }); - - on("after:run", async (results) => { - // Your custom logic... - - return argosAfterRun(config, results, argosConfig); - }); - }, - }, -}); -``` - -## API Overview - -### cy.argosScreenshot([name][, options]) - -- `name`: Unique name for the screenshot. -- `options`: Explore [cy.screenshot command options](https://docs.cypress.io/api/commands/screenshot) for details. -- `options.element`: Use an ElementHandle or string selector to capture a specific element's screenshot. -- `options.viewports`: Define specific viewports for capturing screenshots. More on [viewports configuration](/viewports). -- `options.argosCSS`: Specific CSS applied during the screenshot process. More on [injecting CSS](/injecting-css) -- `options.threshold`: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Default to `0.5`. -- `options.stabilize`: Wait for the UI to stabilize before taking the screenshot. Set to `false` to disable stabilization. Pass an object to customize the stabilization. Default to `true`. -- `options.stabilize.disableSpellCheck`: Disable spell check before taking the screenshot. Default to `true`. -- `options.stabilize.fontAntialiasing`: Force font antialiasing. Default to `true`. -- `options.stabilize.hideCarets`: Hide text carets before taking the screenshot. Default to `true`. -- `options.stabilize.hideScrollbars`: Hide scrollbars before taking the screenshot. Default to `true`. -- `options.stabilize.loadImageSrcset`: Force the loading of images with `srcset` attributes when the viewport changes. Default to `true`. -- `options.stabilize.roundImageSize`: Round image sizes to the nearest integer. Default to `true`. -- `options.stabilize.stabilizeSticky`: Stabilize sticky and fixed elements by switching to `position: absolute`. Default to `true`. -- `options.stabilize.waitForAriaBusy`: Wait for the `aria-busy` attribute to be removed from the document. Default to `true`. -- `options.stabilize.waitForFonts`: Wait for fonts to be loaded. Default to `true`. -- `options.stabilize.waitForImages`: Wait for images to be loaded. Default to `true`. -- `options.tag`: Tag or array of tags to attach to the screenshot for filtering in Argos. - -## Helper Attributes for Visual Testing - -For tailored visual testing, the `data-visual-test` attributes provide control over how elements appear in Argos screenshots. This can be especially useful for obscuring or modifying elements with dynamic content, like dates. - -- `[data-visual-test="transparent"]`: Renders the element transparent (`visiblity: hidden`). -- `[data-visual-test="removed"]`: Removes the element from view (`display: none`). -- `[data-visual-test="blackout"]`: Masks the element with a blackout effect. -- `[data-visual-test-no-radius]`: Strips the border radius from the element. - -**Example: Using a helper attribute to hide a div from the captured screenshot:** - -```html -...
-```
-
-### registerArgosTask(on, config[, options])
-
-- `on`: Cypress plugin events.
-- `config`: Cypress config.
-- `options`: All [upload parameters](https://js-sdk-reference.argos-ci.com/interfaces/UploadParameters.html).
-- `options.uploadToArgos`: Upload results and create a build on Argos, `true` by default.
-
-```ts title="cypress.config.js"
-const { defineConfig } = require("cypress");
-const { registerArgosTask } = require("@argos-ci/cypress/task");
-
-module.exports = defineConfig({
- // setupNodeEvents can be defined in either
- // the e2e or component configuration
- e2e: {
- async setupNodeEvents(on, config) {
- registerArgosTask(on, config, {
- uploadToArgos: !!process.env.CI,
- });
-
- // include any other plugin code...
- },
- },
-});
-```
-
-### argosAfterScreenshot(config, details[, options])
-
-Cypress "after:screenshot" event handler.
-
-- `config`: Cypress config.
-- `details`: Screenshot details provided by Cypress.
-- `options`: All [upload parameters](https://js-sdk-reference.argos-ci.com/interfaces/UploadParameters.html).
-- `options.uploadToArgos`: Upload results and create a build on Argos, `true` by default.
-
-```ts title="cypress.config.js"
-const { defineConfig } = require("cypress");
-const { argosAfterScreenshot } = require("@argos-ci/cypress/task");
-
-module.exports = defineConfig({
- // setupNodeEvents can be defined in either
- // the e2e or component configuration
- e2e: {
- async setupNodeEvents(on, config) {
- on("after:screenshot", async (details) => {
- // Your custom logic...
-
- return argosAfterScreenshot(config, details, {
- uploadToArgos: !!process.env.CI,
- });
- });
-
- // include any other plugin code...
- },
- },
-});
-```
-
-### argosAfterRun(config, results[, options])
-
-Cypress "after:run" event handler.
-
-- `config`: Cypress config.
-- `results`: Run results provided by Cypress.
-- `options`: All [upload parameters](https://js-sdk-reference.argos-ci.com/interfaces/UploadParameters.html).
-- `options.uploadToArgos`: Upload results and create a build on Argos, `true` by default.
-
-```ts title="cypress.config.js"
-const { defineConfig } = require("cypress");
-const { argosAfterRun } = require("@argos-ci/cypress/task");
-
-module.exports = defineConfig({
- // setupNodeEvents can be defined in either
- // the e2e or component configuration
- e2e: {
- async setupNodeEvents(on, config) {
- on("after:run", async (results) => {
- // Your custom logic...
-
- await argosAfterRun(config, results, {
- uploadToArgos: !!process.env.CI,
- });
- });
-
- // include any other plugin code...
- },
- },
-});
-```
-
-## Troubleshooting
-
-### Error while importing `@argos-ci/cypress/task` in `cypress.config.ts`
-
-To address the `ts(1479)` error when importing `@argos-ci/cypress/task` in your `cypress.config.ts`, you have two main strategies:
-
-1. Update your `tsconfig.json` by setting `moduleResolution` to `"Bundler"`. This method leverages TypeScript's support for newer module resolution strategies, aligning with Node.js's `exports` feature used by Argos to distribute optimized SDKs.
-
-2. Alternatively, suppress the error in `cypress.config.ts` by adding the line `// @ts-expect-error moduleResolution` right above the import statement. This tells TypeScript to expect an error at this line and ignore it, offering a quick workaround without adjusting your project's module resolution strategy.
-
-The first option is a more comprehensive solution, dealing with the TypeScript bug through adopting the new `moduleResolution: "Bundler"` setting, which is designed for such cases. The second option is simpler and quicker but bypasses the issue rather than solving it at its core.
-
-### Viewports option not working
-
-When running Cypress in headless mode, the [Cypress.viewport](https://docs.cypress.io/api/commands/viewport) command (used internally by `@argos-ci/cypress`) may not behave as expected. This is because headless browsers don’t render a visible viewport, which can result in incorrect or inconsistent screenshots.
-
-To ensure a consistent viewport size, configure it via `setupNodeEvents` in your `cypress.config.js`. This approach sets the viewport before the browser launches, avoiding visual regressions.
-
-```ts title="cypress.config.js"
-import { defineConfig } from "cypress";
-
-export default defineConfig({
- // setupNodeEvents can be defined in either
- // the e2e or component configuration
- e2e: {
- setupNodeEvents(on, config) {
- on("before:browser:launch", (browser, launchOptions) => {
- if (browser.name === "chrome" && browser.isHeadless) {
- // fullPage screenshot size is 1400x1200 on non-retina screens
- // and 2800x2400 on retina screens
- launchOptions.args.push("--window-size=1400,1200");
-
- // force screen to be non-retina (1400x1200 size)
- launchOptions.args.push("--force-device-scale-factor=1");
-
- // force screen to be retina (2800x2400 size)
- // launchOptions.args.push('--force-device-scale-factor=2')
- }
-
- if (browser.name === "electron" && browser.isHeadless) {
- // fullPage screenshot size is 1400x1200
- launchOptions.preferences.width = 1400;
- launchOptions.preferences.height = 1200;
- }
-
- if (browser.name === "firefox" && browser.isHeadless) {
- // menubars take up height on the screen
- // so fullPage screenshot size is 1400x1126
- launchOptions.args.push("--width=1400");
- launchOptions.args.push("--height=1200");
- }
-
- return launchOptions;
- });
- },
- },
-});
-```
-
-Reference: [Cypress Docs – Set screen size when running headless](https://docs.cypress.io/api/node-events/browser-launch-api#Set-screen-size-when-running-headless)
-
-## Additional Resources
-
-- [Quickstart with Argos + Cypress](/quickstart/cypress)
-- [Example of Argos + Cypress](https://github.com/argos-ci/argos-javascript/tree/main/examples/cypress)
-- [@argos-ci/cypress on GitHub](https://github.com/argos-ci/argos-javascript/tree/main/packages/cypress)
-- [@argos-ci/cypress on npm](https://www.npmjs.com/package/@argos-ci/cypress)
diff --git a/packages/cypress/package.json b/packages/cypress/package.json
index 1f577ce7..5097f1cc 100644
--- a/packages/cypress/package.json
+++ b/packages/cypress/package.json
@@ -9,7 +9,7 @@
"url": "https://github.com/argos-ci/argos-javascript.git",
"directory": "packages/cypress"
},
- "homepage": "https://argos-ci.com/docs/cypress",
+ "homepage": "https://argos-ci.com/docs/sdks-reference/cypress",
"bugs": {
"url": "https://github.com/argos-ci/argos-javascript/issues"
},
diff --git a/packages/cypress/src/support.ts b/packages/cypress/src/support.ts
index 26518dff..acc61691 100644
--- a/packages/cypress/src/support.ts
+++ b/packages/cypress/src/support.ts
@@ -57,7 +57,7 @@ declare global {
/**
* Stabilize the UI and takes a screenshot of the application under test.
*
- * @see https://argos-ci.com/docs/cypress#api-overview
+ * @see https://argos-ci.com/docs/sdks-reference/cypress
* @example
* cy.argosScreenshot("my-screenshot")
* cy.get(".post").argosScreenshot()
diff --git a/packages/gitlab/README.md b/packages/gitlab/README.md
index b61058bf..eb93884b 100644
--- a/packages/gitlab/README.md
+++ b/packages/gitlab/README.md
@@ -1,15 +1,42 @@
-_Argos is a visual testing solution that fits in your workflow to avoid visual regression. Takes screenshots on each commit and be notified if something changes._
+The open source visual testing platform for AI-native engineering teams.
# Argos GitLab -Argos GitLab utilities to setup GitLab in self-hosted mode. +GitLab utilities to report Argos build statuses back to your merge requests when running Argos with a self-managed GitLab instance. [](https://www.npmjs.com/package/@argos-ci/gitlab) [](https://www.npmjs.com/package/@argos-ci/gitlab) [](https://www.npmjs.com/package/@argos-ci/gitlab) + +Visit the [GitLab integration documentation](https://argos-ci.com/docs/learn/integrations/gitlab-integration) for the full setup guide. + +## Usage + +Run the `argos-gitlab update-statuses` command in your GitLab CI pipeline. It waits for the Argos builds of the current commit to complete and reports their status to the related merge request: + +```yaml +# .gitlab-ci.yml +argos-status: + script: + - npx @argos-ci/gitlab update-statuses + variables: + ARGOS_TOKEN: $ARGOS_TOKEN + ARGOS_GITLAB_TOKEN: $ARGOS_GITLAB_TOKEN +``` + +`ARGOS_GITLAB_TOKEN` is a GitLab access token allowed to post commit statuses. The `CI_PROJECT_ID`, `CI_SERVER_URL`, and `CI_COMMIT_SHA` variables are provided by GitLab CI automatically. + +## Links + +- [GitLab integration guide](https://argos-ci.com/docs/learn/integrations/gitlab-integration) +- [Official Docs](https://argos-ci.com/docs) +- [Discord](https://argos-ci.com/discord) diff --git a/packages/gitlab/package.json b/packages/gitlab/package.json index 7ae403c8..da01d429 100644 --- a/packages/gitlab/package.json +++ b/packages/gitlab/package.json @@ -9,7 +9,7 @@ "url": "https://github.com/argos-ci/argos-javascript.git", "directory": "packages/gitlab" }, - "homepage": "https://argos-ci.com/docs/gitlab", + "homepage": "https://argos-ci.com/docs/learn/integrations/gitlab-integration", "bugs": { "url": "https://github.com/argos-ci/argos-javascript/issues" }, diff --git a/packages/playwright/README.md b/packages/playwright/README.md index 22d213e2..cf1c18f3 100644 --- a/packages/playwright/README.md +++ b/packages/playwright/README.md @@ -7,7 +7,7 @@ -The open source visual testing plaform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
# Official Argos Playwright integration @@ -15,9 +15,56 @@ [](https://www.npmjs.com/package/@argos-ci/playwright) [](https://www.npmjs.com/package/@argos-ci/playwright) -Visit [argos-ci.com/docs/playwright](https://argos-ci.com/docs/playwright) for guides, API and more. +Capture stable Argos screenshots from your [Playwright](https://playwright.dev/) tests, and report failure screenshots and traces to Argos. + +Visit the [Playwright SDK documentation](https://argos-ci.com/docs/sdks-reference/playwright) for guides, the API reference, and more. + +## Installation + +```sh +npm install --save-dev @argos-ci/playwright +``` + +## Usage + +Set up the Argos reporter in your Playwright config: + +```ts +// playwright.config.ts +import { defineConfig } from "@playwright/test"; +import { createArgosReporterOptions } from "@argos-ci/playwright/reporter"; + +export default defineConfig({ + // ... other configuration + reporter: [ + // Use "dot" reporter on CI, "list" otherwise (Playwright default). + process.env.CI ? ["dot"] : ["list"], + + // Add the Argos reporter. + [ + "@argos-ci/playwright/reporter", + // Upload the screenshots to Argos only on CI. + createArgosReporterOptions({ uploadToArgos: !!process.env.CI }), + ], + ], +}); +``` + +Then capture stable screenshots with `argosScreenshot` in your tests: + +```ts +// tests/example.spec.ts +import { test } from "@playwright/test"; +import { argosScreenshot } from "@argos-ci/playwright"; + +test("screenshot homepage", async ({ page }) => { + await page.goto("http://localhost:3000"); + await argosScreenshot(page, "homepage"); +}); +``` ## Links -- [Official SDK Docs](https://argos-ci.com/docs/) +- [Official SDK Docs](https://argos-ci.com/docs/sdks-reference/playwright) +- [Quickstart](https://argos-ci.com/docs/quickstart/playwright-quickstart) - [Discord](https://argos-ci.com/discord) diff --git a/packages/playwright/docs/index.mdx b/packages/playwright/docs/index.mdx deleted file mode 100644 index 9e34e69b..00000000 --- a/packages/playwright/docs/index.mdx +++ /dev/null @@ -1,381 +0,0 @@ ---- -title: Playwright -slug: /playwright ---- - -# Argos Playwright SDK - -Improve test debugging and boost your visual testing capabilities by combining Argos with your [Playwright](https://playwright.dev/) tests. - -## Get started - -Please refer to our [Quickstart guide](/quickstart/playwright) to get started with Argos and Playwright. - -## Setup Visual Testing - -Argos presents a significant advantage over traditional Playwright visual tests with its streamlined approach to managing and reviewing test results: - -- **Visual Testing on CI**: With Argos, there's no need to run tests locally or commit screenshots to your repository. This not only saves time but also keeps your repository clean and focused on code rather than binary assets. -- **Fluid UI for Comparison**: Argos intuitive interface makes it easy to spot discrepancies and understand visual changes without the need for cumbersome manual checks. -- **Enhanced Stabilization**: The Argos integration with Playwright takes visual testing to the next level by ensuring stability and consistency in the screenshots captured. Fonts, images, animations, loaders, everything is just stable. - -To enable Visual Testing with Playwright, first you have to setup the Argos reporter in your Playwright config: - -```ts title="playwright.config.ts" -import { defineConfig } from "@playwright/test"; -import { createArgosReporterOptions } from "@argos-ci/playwright/reporter"; - -export default defineConfig({ - // ... other configurations - - // Setup Argos reporter to send screenshots and traces to Argos. - reporter: [ - // Use "dot" reporter on CI, "list" otherwise (Playwright default). - process.env.CI ? ["dot"] : ["list"], - - // Add Argos reporter. - [ - "@argos-ci/playwright/reporter", - // Upload only on CI. - createArgosReporterOptions({ uploadToArgos: !!process.env.CI }), - ], - ], -}); -``` - -And use `argosScreenshot` helper to capture stable screenshots in your E2E tests: - -```ts title="tests/example.spec.ts" -import { test } from "@playwright/test"; -import { argosScreenshot } from "@argos-ci/playwright"; - -test("screenshot homepage", async ({ page }) => { - await page.goto("http://localhost:3000"); - await argosScreenshot(page, "homepage"); -}); -``` - -## Setup Tests Debugging - -The Argos Playwright reporter automatically reports failure screenshots and playwright traces. You can access them directly in Argos UI. If you are tired to download traces from artifact and run a command to see them, it is the solution for you. - -- **Failure Screenshots**: View failure screenshots from your CI tests directly in Argos. No extra steps, just immediate clarity where you need it most. -- **Playwright Traces**: “Time travel” through your failing tests with remote Playwright traces. Gain a complete, step-by-step visual journey to the heart of any test issue. - -To enable Test Debugging, you have to add Argos reporter and to turn on [Playwright test use options](https://playwright.dev/docs/test-use-options) in your Playwright config: - -```ts title="playwright.config.ts" -import { defineConfig } from "@playwright/test"; -import { createArgosReporterOptions } from "@argos-ci/playwright/reporter"; - -export default defineConfig({ - // ... other configurations - - // Setup Argos reporter to send screenshots and traces to Argos. - reporter: [ - // Use "dot" reporter on CI, "list" otherwise (Playwright default). - process.env.CI ? ["dot"] : ["list"], - - // Add Argos reporter. - [ - "@argos-ci/playwright/reporter", - // Upload only on CI. - createArgosReporterOptions({ uploadToArgos: !!process.env.CI }), - ], - ], - - // Setup recording option to enable test debugging features. - use: { - // Collect trace when retrying the failed test. - trace: "on-first-retry", - - // Capture screenshot after each test failure. - screenshot: "only-on-failure", - }, -}); -``` - -## Tests Sharding - -Argos seamlessly integrates with [Playwright test sharding](https://playwright.dev/docs/test-sharding), enabling efficient test distribution without the need for manual configuration. [Argos Sharding/Parallel mode](/parallel-testing) is automatically configured for you. - -Argos also supports [Currents orchestration](https://currents.dev/) using [Argos parallel + finalize](/parallel-testing). - -## Helper Attributes for Visual Testing - -For tailored visual testing, the `data-visual-test` attributes provide control over how elements appear in Argos screenshots. This can be especially useful for obscuring or modifying elements with dynamic content, like dates. - -- `[data-visual-test="transparent"]`: Renders the element transparent (`visiblity: hidden`). -- `[data-visual-test="removed"]`: Removes the element from view (`display: none`). -- `[data-visual-test="blackout"]`: Masks the element with a blackout effect. -- `[data-visual-test-no-radius]`: Strips the border radius from the element. - -**Example: Using a helper attribute to hide a div from the captured screenshot:** - -```html -...
-```
-
-## Create multiple Argos builds from a single suite of tests
-
-To generate multiple Argos builds from a single suite of Playwright tests, use a dynamic `buildName`. This object contains two properties:
-
-- `values`: An array of possible values returned by the `get` function.
-- `get`: A function that takes a [test case](https://playwright.dev/docs/api/class-testcase) as an argument and returns the build name.
-
-```ts title="playwright.config.ts"
-import { defineConfig } from "@playwright/test";
-import { createArgosReporterOptions } from "@argos-ci/playwright/reporter";
-
-export default defineConfig({
- // ... other configurations
-
- reporter: [
- // Use "dot" reporter on CI, "list" otherwise (Playwright default).
- process.env.CI ? ["dot"] : ["list"],
-
- // Argos reporter
- [
- "@argos-ci/playwright/reporter",
- createArgosReporterOptions({
- uploadToArgos: !!process.env.CI,
- buildName: {
- values: ["app", "website"],
- // Split Argos build based on Playwright tags
- // Learn more about Playwright tags: https://playwright.dev/docs/test-annotations#tag-tests
- get: (test) => (test.tags.includes("@website") ? "website" : "app"),
- },
- }),
- ],
- ],
-});
-```
-
-## Debug flaky tests
-
-To debug flaky tests, Argos supports using the [Playwright --repeat-each option](https://playwright.dev/docs/test-cli#reference). This runs each test multiple times to detect discrepancies.
-
-```sh
-npm exec -- playwright test --repeat-each 5
-```
-
-## Configure Content-Security-Policy (CSP)
-
-To stabilize tests, Argos injects a script before taking screenshots. This script may conflict with your CSP settings. To resolve this issue, you have two options:
-
-### 1. Allow the Argos script in your CSP
-
-The `@argos-ci/playwright` package provides a `getCSPScriptHash` method to retrieve the hash of the script injected by Argos. Additionally, Argos requires the `'unsafe-eval'` directive to function properly.
-
-To use this method, you need to be able to inject CSP headers into your server. Here's an example in a Playwright configuration:
-
-```ts
-import { defineConfig } from "@playwright/test";
-import { getCSPScriptHash } from "@argos-ci/playwright";
-
-export default defineConfig({
- webServer: {
- command: "node my-app.js",
- port: 3000,
- env: {
- CSP_SCRIPT_SRC: `${getCSPScriptHash()},'unsafe-eval'`,
- },
- },
-});
-```
-
-### 2. Configure Playwright to bypass CSP
-
-If you do not have the flexibility to add custom CSP headers for Playwright test execution, you can [configure Playwright to bypass CSP](https://playwright.dev/docs/api/class-testoptions#test-options-bypass-csp) in your Playwright configuration:
-
-```ts
-import { defineConfig } from "@playwright/test";
-
-export default defineConfig({
- use: {
- bypassCSP: true,
- },
-});
-```
-
-## Set a Preview URL
-
-Argos displays the URL of the page when a screenshot is taken, helping you understand the screenshot’s context in the Argos UI. If you run tests locally and deploy your pull requests (PRs) to a preview URL, you can link the two by setting the `ARGOS_PREVIEW_URL` environment variable or configuring the `previewUrl` option in the Argos reporter.
-
-### Example Configuration
-
-```ts title="playwright.config.ts"
-import { defineConfig } from "@playwright/test";
-import { createArgosReporterOptions } from "@argos-ci/playwright/reporter";
-
-export default defineConfig({
- reporter: [
- [
- "@argos-ci/playwright/reporter",
- createArgosReporterOptions({
- previewUrl: {
- baseUrl: "https://my-site.com", // Use a dynamic value here for different environments if needed.
- },
- }),
- ],
- ],
-});
-```
-
-## Test annotations
-
-Argos supports [annotations](https://playwright.dev/docs/test-annotations) added to your tests, providing additional context and information. All annotations are displayed in Argos Build UI, except those where type starts with \_ symbol.
-
-### Example Usage
-
-```ts
-import { test, expect } from "@playwright/test";
-
-test(
- "test login page",
- {
- annotation: {
- type: "visual-test",
- description:
- "Critical UI path – ensures login form fields and CTA button align correctly on desktop viewport. Related to regression #1423.",
- },
- },
- async ({ page }) => {
- // ...
- },
-);
-```
-
-## ARIA Snapshots
-
-Argos allows you to capture ARIA snapshots alongside your screenshots, enhancing accessibility testing. ARIA snapshots provide a structured representation of the page's accessible elements, which can be invaluable for identifying accessibility issues.
-
-### Capture alongside screenshots
-
-You can set `ariaSnapshot: true` in the `argosScreenshot` options to capture an ARIA snapshot along with the screenshot.
-
-```ts title="tests/example.spec.ts"
-import { test } from "@playwright/test";
-import { argosScreenshot } from "@argos-ci/playwright";
-
-test("screenshot homepage with ARIA snapshot", async ({ page }) => {
- await page.goto("http://localhost:3000");
- await argosScreenshot(page, "homepage", { ariaSnapshot: true });
-});
-```
-
-:::note
-
-When using the `viewports` option, an ARIA snapshot is captured for each viewport.
-
-:::
-
-### Capture only ARIA snapshot
-
-It is also possible to capture only an ARIA snapshot without a screenshot using the `argosAriaSnapshot` function:
-
-```ts title="tests/example.spec.ts"
-import { test } from "@playwright/test";
-import { argosAriaSnapshot } from "@argos-ci/playwright";
-
-test("capture ARIA snapshot of homepage", async ({ page }) => {
- await page.goto("http://localhost:3000");
- await argosAriaSnapshot(page, "homepage-aria-snapshot");
-});
-```
-
-### Billing
-
-Each ARIA snapshot counts as an additional screenshot for billing.
-
-## API Overview
-
-### argosScreenshot(handler, name[, options])
-
-- `handler`: Instance of the [Playwright Page](https://playwright.dev/docs/api/class-page) or [Playwright Frame](https://playwright.dev/docs/api/class-frame).
-- `name`: Unique name for the screenshot.
-- `options`: Explore [`Page.screenshot` command options](https://playwright.dev/docs/api/class-page#page-screenshot) for details.
-- `options.element`: Use a [`Locator`](https://playwright.dev/docs/api/class-locator) or a string selector to capture a specific element's screenshot.
-- `options.viewports`: Define specific viewports for capturing screenshots. More on [viewports configuration](/viewports).
-- `options.ariaSnapshot`: Capture an ARIA snapshot along with the screenshot. More on [ARIA snapshots](#aria-snapshots).
-- `options.argosCSS`: Specific CSS applied during the screenshot process. More on [injecting CSS](/injecting-css)
-- `options.disableHover`: Disable hover effects by moving the mouse to the top-left corner of the page. Default to `true`.
-- `options.threshold`: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Default to `0.5`.
-- `options.root`: Folder where the screenshots will be saved if not using the Argos reporter. Default to `./screenshots`.
-- `options.stabilize`: Wait for the UI to stabilize before taking the screenshot. Set to `false` to disable stabilization. Pass an object to customize the stabilization. Default to `true`.
-- `options.stabilize.disableSpellCheck`: Disable spell check before taking the screenshot. Default to `true`.
-- `options.stabilize.fontAntialiasing`: Force font antialiasing. Default to `true`.
-- `options.stabilize.hideCarets`: Hide text carets before taking the screenshot. Default to `true`.
-- `options.stabilize.hideScrollbars`: Hide scrollbars before taking the screenshot. Default to `true`.
-- `options.stabilize.loadImageSrcset`: Force the loading of images with `srcset` attributes when the viewport changes. Default to `true`.
-- `options.stabilize.roundImageSize`: Round image sizes to the nearest integer. Default to `true`.
-- `options.stabilize.stabilizeSticky`: Stabilize sticky and fixed elements by switching to `position: absolute`. Default to `true`.
-- `options.stabilize.waitForAriaBusy`: Wait for the `aria-busy` attribute to be removed from the document. Default to `true`.
-- `options.stabilize.waitForFonts`: Wait for fonts to be loaded. Default to `true`.
-- `options.stabilize.waitForImages`: Wait for images to be loaded. Default to `true`.
-- `options.beforeScreenshot`: Run a function before taking the screenshot. When using viewports, this function will run before taking sreenshots on each viewport.
-- `options.afterScreenshot`: Run a function after taking the screenshot. When using viewports, this function will run after taking sreenshots on each viewport.
-- `options.tag`: Tag or array of tags to attach to the screenshot for filtering in Argos.
-
-Playwright test tags (from `test.describe` or `test` annotations) are automatically captured in the metadata.
-
-Unlike [Playwright's `screenshot` method](https://playwright.dev/docs/api/class-page#page-screenshot), set `fullPage` option to `true` by default. Feel free to override this option if you prefer partial screenshots of your pages.
-
-### argosAriaSnapshot(handler, name[, options])
-
-- `handler`: Instance of the [Playwright Page](https://playwright.dev/docs/api/class-page) or [Playwright Frame](https://playwright.dev/docs/api/class-frame).
-- `name`: Unique name for the screenshot.
-- `options.element`: Use a [`Locator`](https://playwright.dev/docs/api/class-locator) or a string selector to capture a specific element's screenshot.
-- `options.root`: Folder where the screenshots will be saved if not using the Argos reporter. Default to `./screenshots`.
-- `options.timeout`: Maximum time in milliseconds. Defaults to `0` - no timeout.
-- `options.stabilize`: Wait for the UI to stabilize before taking the screenshot. Set to `false` to disable stabilization. Pass an object to customize the stabilization. Default to `true`.
-- `options.stabilize.disableSpellCheck`: Disable spell check before taking the screenshot. Default to `true`.
-- `options.stabilize.fontAntialiasing`: Force font antialiasing. Default to `true`.
-- `options.stabilize.hideCarets`: Hide text carets before taking the screenshot. Default to `true`.
-- `options.stabilize.hideScrollbars`: Hide scrollbars before taking the screenshot. Default to `true`.
-- `options.stabilize.loadImageSrcset`: Force the loading of images with `srcset` attributes when the viewport changes. Default to `true`.
-- `options.stabilize.roundImageSize`: Round image sizes to the nearest integer. Default to `true`.
-- `options.stabilize.stabilizeSticky`: Stabilize sticky and fixed elements by switching to `position: absolute`. Default to `true`.
-- `options.stabilize.waitForAriaBusy`: Wait for the `aria-busy` attribute to be removed from the document. Default to `true`.
-- `options.stabilize.waitForFonts`: Wait for fonts to be loaded. Default to `true`.
-- `options.stabilize.waitForImages`: Wait for images to be loaded. Default to `true`.
-
-### getCSPScriptHash()
-
-Returns the Content-Security-Policy script hash used by Argos (ex: `'sha256-xaC9wWpMVRiAXSfhxhP+Wyqkw0mgO+MIrHuzmMPIxEI='`).
-
-### Playwright reporter
-
-The Argos reporter offers extensive configuration options. Specifically, all [upload parameters](https://js-sdk-reference.argos-ci.com/interfaces/UploadParameters.html) are available for customizing the reporter.
-
-The `createArgosReporterOptions` ensures that your options are correctly typed.
-
-```ts title="playwright.config.ts"
-import { defineConfig } from "@playwright/test";
-import { createArgosReporterOptions } from "@argos-ci/playwright/reporter";
-
-export default defineConfig({
- // ... other configurations
-
- reporter: [
- // Use "dot" reporter on CI, "list" otherwise (Playwright default).
- process.env.CI ? ["dot"] : ["list"],
-
- // Argos reporter
- [
- "@argos-ci/playwright/reporter",
- createArgosReporterOptions({
- uploadToArgos: !!process.env.CI,
- buildName: "custom-build-name",
- }),
- ],
- ],
-});
-```
-
-## Additional Resources
-
-- [Quickstart with Argos + Playwright](/quickstart/playwright)
-- [Argos + Playwright example](https://github.com/argos-ci/argos-javascript/tree/main/examples/playwright)
-- [@argos-ci/playwright on GitHub](https://github.com/argos-ci/argos-javascript/tree/main/packages/playwright)
-- [@argos-ci/playwright on npm](https://www.npmjs.com/package/@argos-ci/playwright)
diff --git a/packages/playwright/package.json b/packages/playwright/package.json
index 0af88bc3..41408dde 100644
--- a/packages/playwright/package.json
+++ b/packages/playwright/package.json
@@ -9,7 +9,7 @@
"url": "https://github.com/argos-ci/argos-javascript.git",
"directory": "packages/playwright"
},
- "homepage": "https://argos-ci.com/docs/playwright",
+ "homepage": "https://argos-ci.com/docs/sdks-reference/playwright",
"bugs": {
"url": "https://github.com/argos-ci/argos-javascript/issues"
},
diff --git a/packages/playwright/src/screenshot.ts b/packages/playwright/src/screenshot.ts
index 35be9213..b5971855 100644
--- a/packages/playwright/src/screenshot.ts
+++ b/packages/playwright/src/screenshot.ts
@@ -133,7 +133,7 @@ export type ArgosScreenshotOptions = {
*
* @example
* argosScreenshot(page, "my-screenshot")
- * @see https://argos-ci.com/docs/playwright#api-overview
+ * @see https://argos-ci.com/docs/sdks-reference/playwright
*/
export async function argosScreenshot(
/**
diff --git a/packages/puppeteer/README.md b/packages/puppeteer/README.md
index 2ced9bdc..c74ac67b 100644
--- a/packages/puppeteer/README.md
+++ b/packages/puppeteer/README.md
@@ -1,10 +1,13 @@
-_Argos is a visual testing solution that fits in your workflow to avoid visual regression. Takes screenshots on each commit and be notified if something changes._
+The open source visual testing platform for AI-native engineering teams.
# Official Argos Puppeteer integration @@ -12,9 +15,41 @@ _Argos is a visual testing solution that fits in your workflow to avoid visual r [](https://www.npmjs.com/package/@argos-ci/puppeteer) [](https://www.npmjs.com/package/@argos-ci/puppeteer) -Visit [argos-ci.com/docs/puppeteer](https://argos-ci.com/docs/puppeteer) for guides, API and more. +Capture stable Argos screenshots from your [Puppeteer](https://github.com/puppeteer/puppeteer) tests. + +Visit the [Puppeteer SDK documentation](https://argos-ci.com/docs/sdks-reference/puppeteer) for guides, the API reference, and more. + +## Installation + +Install the SDK alongside the [Argos CLI](https://argos-ci.com/docs/sdks-reference/argos-command-line-interface-cli), which uploads the screenshots to Argos: + +```sh +npm install --save-dev @argos-ci/puppeteer @argos-ci/cli +``` + +## Usage + +Use `argosScreenshot` to stabilize the UI and capture a screenshot: + +```ts +import puppeteer from "puppeteer"; +import { argosScreenshot } from "@argos-ci/puppeteer"; + +const browser = await puppeteer.launch(); +const page = await browser.newPage(); +await page.goto("http://localhost:3000"); +await argosScreenshot(page, "homepage"); +await browser.close(); +``` + +Screenshots are saved locally (in `./screenshots/argos` by default). Upload them to Argos with the Argos CLI, usually at the end of your CI job: + +```sh +npx @argos-ci/cli upload ./screenshots +``` ## Links -- [Official SDK Docs](https://argos-ci.com/docs/) +- [Official SDK Docs](https://argos-ci.com/docs/sdks-reference/puppeteer) +- [Quickstart](https://argos-ci.com/docs/quickstart/puppeteer-quickstart) - [Discord](https://argos-ci.com/discord) diff --git a/packages/puppeteer/docs/index.mdx b/packages/puppeteer/docs/index.mdx deleted file mode 100644 index 2617e954..00000000 --- a/packages/puppeteer/docs/index.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Puppeteer -slug: /puppeteer ---- - -# Argos Puppeteer SDK - -Integrating Argos with your [Puppeteer](https://github.com/puppeteer/puppeteer) tests to enable visual testing on your application. - -Puppeteer already offers a command to take screenshots. The official Argos Puppeteer integration uses it but also does several things: - -- Ensuring all images are fully loaded. -- Ensuring all fonts are rendered. -- Confirming the absence of any `aria-busy` (loading) elements on the page. -- Concealing scrollbars. -- Obscuring text cursors or carets. -- Providing CSS utilities to simplify content hiding. - -## Installation - -### 1. Install package - -``` -npm install --save-dev @argos-ci/cli @argos-ci/puppeteer -``` - -### 2. Use in your tests - -`argosScreenshot` command stabilizes the UI and takes a screenshot. - -_How to take a screenshot with `argosScreenshot` command_ - -```js -import puppeteer from "puppeteer"; -import { argosScreenshot } from "@argos-ci/puppeteer"; - -describe("Integration test with visual testing", () => { - it("loads the homepage", async () => { - const browser = await puppeteer.launch(); - const page = await browser.newPage(); - await page.goto(TEST_URL); - await argosScreenshot(page, this.test.fullTitle()); - }); -}); -``` - -Screenshots are stored in `screenshots/argos` folder, relative to current directory. - -## API Overview - -### argosScreenshot(page, name[, options]) - -- `page` - A `puppeteer` page instance -- `name` - The screenshot name; must be unique. If ends by `.png` we treat it as a path. -- `options` - See [Page.screenshot command options](https://pptr.dev/api/puppeteer.page.screenshot) -- `options.element` - Accept an ElementHandle or a string selector to screenshot an element -- `options.viewports` - Specifies the viewports for which to capture screenshots. See [viewports configuration](/viewports). -- `options.argosCSS`: Specific CSS applied during the screenshot process. More on [injecting CSS](/injecting-css) -- `options.disableHover`: Disable hover effects by moving the mouse to the top-left corner of the page. Default to `true`. -- `options.threshold`: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Default to `0.5`. -- `options.stabilize`: Wait for the UI to stabilize before taking the screenshot. Set to `false` to disable stabilization. Pass an object to customize the stabilization. Default to `true`. -- `options.stabilize.disableSpellCheck`: Disable spell check before taking the screenshot. Default to `true`. -- `options.stabilize.fontAntialiasing`: Force font antialiasing. Default to `true`. -- `options.stabilize.hideCarets`: Hide text carets before taking the screenshot. Default to `true`. -- `options.stabilize.hideScrollbars`: Hide scrollbars before taking the screenshot. Default to `true`. -- `options.stabilize.loadImageSrcset`: Force the loading of images with `srcset` attributes when the viewport changes. Default to `true`. -- `options.stabilize.roundImageSize`: Round image sizes to the nearest integer. Default to `true`. -- `options.stabilize.stabilizeSticky`: Stabilize sticky and fixed elements by switching to `position: absolute`. Default to `true`. -- `options.stabilize.waitForAriaBusy`: Wait for the `aria-busy` attribute to be removed from the document. Default to `true`. -- `options.stabilize.waitForFonts`: Wait for fonts to be loaded. Default to `true`. -- `options.stabilize.waitForImages`: Wait for images to be loaded. Default to `true`. -- `options.tag`: Tag or array of tags to attach to the screenshot for filtering in Argos. - -Unlike [Puppeteer's `screenshot` method](https://playwright.dev/docs/api/class-page#page-screenshot), `argosScreenshot` set `fullPage` option to `true` by default. Feel free to override this option if you prefer partial screenshots of your pages. - -## Helper Attributes for Visual Testing - -For tailored visual testing, the `data-visual-test` attributes provide control over how elements appear in Argos screenshots. This can be especially useful for obscuring or modifying elements with dynamic content, like dates. - -- `[data-visual-test="transparent"]`: Renders the element transparent (`visiblity: hidden`). -- `[data-visual-test="removed"]`: Removes the element from view (`display: none`). -- `[data-visual-test="blackout"]`: Masks the element with a blackout effect. -- `[data-visual-test-no-radius]`: Strips the border radius from the element. - -**Example: Using a helper attribute to hide a div from the captured screenshot:** - -```html -...
-```
-
-## Additional Resources
-
-- [Quickstart with Argos + Puppeteer](/quickstart/puppeteer)
-- [@argos-ci/puppeteer on GitHub](https://github.com/argos-ci/argos-javascript/tree/main/packages/puppeteer)
-- [@argos-ci/puppeteer on npm](https://www.npmjs.com/package/@argos-ci/puppeteer)
diff --git a/packages/puppeteer/package.json b/packages/puppeteer/package.json
index 8919c526..c5cfbda9 100644
--- a/packages/puppeteer/package.json
+++ b/packages/puppeteer/package.json
@@ -9,7 +9,7 @@
"url": "https://github.com/argos-ci/argos-javascript.git",
"directory": "packages/puppeteer"
},
- "homepage": "https://argos-ci.com/docs/puppeteer",
+ "homepage": "https://argos-ci.com/docs/sdks-reference/puppeteer",
"bugs": {
"url": "https://github.com/argos-ci/argos-javascript/issues"
},
diff --git a/packages/puppeteer/src/index.ts b/packages/puppeteer/src/index.ts
index dae41082..844017c9 100644
--- a/packages/puppeteer/src/index.ts
+++ b/packages/puppeteer/src/index.ts
@@ -231,7 +231,7 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}
*
* @example
* argosScreenshot(page, "my-screenshot")
- * @see https://argos-ci.com/docs/puppeteer#api-overview
+ * @see https://argos-ci.com/docs/sdks-reference/puppeteer
*/
export async function argosScreenshot(
/**
diff --git a/packages/storybook/README.md b/packages/storybook/README.md
index 6da9f744..cdb3cf0b 100644
--- a/packages/storybook/README.md
+++ b/packages/storybook/README.md
@@ -7,7 +7,7 @@
-The open source visual testing plaform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
# Official Argos Storybook integration @@ -15,9 +15,52 @@ [](https://www.npmjs.com/package/@argos-ci/storybook) [](https://www.npmjs.com/package/@argos-ci/storybook) -Visit [argos-ci.com/docs/storybook](https://argos-ci.com/docs/storybook) for guides, API and more. +Capture and review visual changes of your [Storybook](https://storybook.js.org/) stories with Argos. It runs your stories in a real browser and uploads a screenshot of each one to Argos in your CI. + +Visit the [Storybook SDK documentation](https://argos-ci.com/docs/sdks-reference/storybook) for guides, the API reference, and more. + +## Installation + +```sh +npm install --save-dev @argos-ci/storybook +``` + +## Usage + +The recommended way to run visual tests is with the [Storybook Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon). Register the Argos plugin in your Vitest config: + +```ts +// vitest.config.ts +import { defineConfig } from "vitest/config"; +import { argosVitestPlugin } from "@argos-ci/storybook/vitest-plugin"; + +export default defineConfig({ + plugins: [ + argosVitestPlugin({ + // Upload the screenshots to Argos only on CI. + uploadToArgos: process.env.CI === "true", + }), + ], +}); +``` + +A screenshot is captured for every story automatically. To capture additional screenshots (for example, at different steps of an interaction), call `argosScreenshot` inside a story's `play` function: + +```ts +// Button.stories.tsx +import { argosScreenshot } from "@argos-ci/storybook/vitest"; + +export const Example: Story = { + play: async (ctx) => { + await argosScreenshot(ctx, "example"); + }, +}; +``` + +> Using the [Storybook Test Runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner) instead? Import `argosScreenshot` from `@argos-ci/storybook/test-runner` and call it from the `postVisit` hook. See the [Test Runner quickstart](https://argos-ci.com/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart). ## Links -- [Official SDK Docs](https://argos-ci.com/docs/) +- [Official SDK Docs](https://argos-ci.com/docs/sdks-reference/storybook) +- [Quickstart](https://argos-ci.com/docs/quickstart/storybook-quickstart) - [Discord](https://argos-ci.com/discord) diff --git a/packages/storybook/docs/index.mdx b/packages/storybook/docs/index.mdx deleted file mode 100644 index 60c1de2b..00000000 --- a/packages/storybook/docs/index.mdx +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: Storybook -slug: /storybook ---- - -# Argos Storybook SDK - -Integrate visual testing with your Storybook seamlessly using Argos. This SDK allows you to capture and review visual changes in your Storybook components directly within your CI. - -## Getting Started - -To get started with Argos and Storybook, check out our quick start guides: - -- [Storybook + Vitest](/quickstart/storybook). -- [Storybook + Test Runner](/quickstart/storybook-test-runner). -- [Storybook Legacy (\The open source visual testing plaform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
# Argos Utilities -Set of utilities used across all Argos SDKs. +Shared utilities used across the Argos SDKs (screenshot metadata, name resolution, and other helpers). [](https://www.npmjs.com/package/@argos-ci/util) [](https://www.npmjs.com/package/@argos-ci/util) [](https://www.npmjs.com/package/@argos-ci/util) +> This package is an internal building block shared by the other Argos SDKs. You usually don't need to install it directly — pick the integration for your test framework instead. + ## Links - [Official Docs](https://argos-ci.com/docs) +- [Discord](https://argos-ci.com/discord) diff --git a/packages/vitest/README.md b/packages/vitest/README.md index 97e218b6..a2c53ee7 100644 --- a/packages/vitest/README.md +++ b/packages/vitest/README.md @@ -7,7 +7,7 @@ -The open source visual testing platform for modern engineering teams.
+The open source visual testing platform for AI-native engineering teams.
# Official Argos Vitest integration @@ -17,7 +17,7 @@ Capture Argos screenshots directly from your [Vitest browser tests](https://vitest.dev/guide/browser/). -Visit [argos-ci.com/docs/vitest](https://argos-ci.com/docs/vitest) for guides, API and more. +Visit [argos-ci.com/docs](https://argos-ci.com/docs) for guides, API and more. ## Requirements @@ -73,5 +73,5 @@ test("Button", async () => { ## Links -- [Official SDK Docs](https://argos-ci.com/docs/) +- [Official SDK Docs](https://argos-ci.com/docs) - [Discord](https://argos-ci.com/discord) diff --git a/packages/vitest/docs/index.mdx b/packages/vitest/docs/index.mdx deleted file mode 100644 index 54d2e12a..00000000 --- a/packages/vitest/docs/index.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Vitest -slug: /vitest ---- - -# Argos Vitest SDK - -Capture and review visual changes straight from your [Vitest browser tests](https://vitest.dev/guide/browser/) with Argos. - -The `@argos-ci/vitest` SDK takes screenshots while Vitest runs your tests in a real browser (using the [Playwright provider](https://vitest.dev/guide/browser/playwright)) and uploads them to Argos in your CI. - -## Requirements - -The SDK runs in [Vitest browser mode](https://vitest.dev/guide/browser/) with the Playwright provider. Install it alongside its peer dependencies: - -```sh -npm install --save-dev @argos-ci/vitest vitest @vitest/browser @vitest/browser-playwright playwright -``` - -## Getting Started - -### 1. Register the plugin - -```ts title="vitest.config.ts" -import { defineConfig } from "vitest/config"; -import { playwright } from "@vitest/browser-playwright"; -import { argosVitestPlugin } from "@argos-ci/vitest/plugin"; - -export default defineConfig({ - plugins: [ - argosVitestPlugin({ - // Upload the screenshots to Argos at the end of the run. - uploadToArgos: process.env.CI === "true", - }), - ], - test: { - browser: { - enabled: true, - headless: true, - provider: playwright(), - instances: [{ browser: "chromium" }], - }, - }, -}); -``` - -### 2. Take screenshots - -```ts title="Button.test.tsx" -import { test } from "vitest"; -import { render } from "vitest-browser-react"; -import { argosScreenshot } from "@argos-ci/vitest"; -import { Button } from "./Button"; - -test("Button", async () => { - render(); - await argosScreenshot("button"); -}); -``` - -## API Overview - -### `@argos-ci/vitest/plugin` - -Exposes the Vitest plugin that registers the `argosScreenshot` browser command and, when -`uploadToArgos` is enabled, the reporter that uploads the screenshots. - -```ts -import { argosVitestPlugin } from "@argos-ci/vitest/plugin"; -``` - -- **`uploadToArgos`**: Set to `true` to upload the screenshots to Argos at the end of the run (default: `false`). -- **`root`**: Folder where the screenshots are written (default: `"./screenshots"`). - -It also accepts every option of the [Playwright `argosScreenshot` function](/playwright#argosscreenshotpage-name-options) (used as defaults for every screenshot, including non-serializable options like `beforeScreenshot`) and every [upload parameter](https://js-sdk-reference.argos-ci.com/interfaces/UploadParameters.html) (e.g. `buildName`). - -### `@argos-ci/vitest` - -Take a screenshot from within a browser test. - -```ts -import { argosScreenshot } from "@argos-ci/vitest"; - -await argosScreenshot("my-screenshot", { - // Take a screenshot of a specific element. - element: "#my-element", - // Capture several viewports. - viewports: [{ width: 320, height: 480 }, "macbook-13"], -}); -``` - -- **`name`**: A unique name for the screenshot. -- **`options`**: Serializable screenshot options. Because they cross the Vitest browser/node boundary, non-serializable options (functions, `Locator` elements) must be set on the plugin instead. - -#### Options - -- **`element`**: String selector of the element to capture. -- **`viewports`**: Viewports to capture (a size, a [preset name](/viewports), or `{ preset, orientation }`). -- **`fullPage`**: Capture the full page instead of fitting the screenshot to the content (default: `false`). -- **`argosCSS`**: Custom CSS evaluated during the screenshot. -- **`threshold`**: Sensitivity threshold between `0` and `1` (default: `0.5`). -- **`tag`**: Tag or array of tags to attach to the screenshot. -- **`ariaSnapshot`**: Capture an ARIA snapshot along with the screenshot (default: `false`). -- **`disableHover`**: Disable hover effects before capturing (default: `true`). -- **`stabilize`**: Wait for the UI to stabilize before capturing (default: `true`). diff --git a/packages/vitest/package.json b/packages/vitest/package.json index efef4574..3f50f85a 100644 --- a/packages/vitest/package.json +++ b/packages/vitest/package.json @@ -9,7 +9,7 @@ "url": "https://github.com/argos-ci/argos-javascript.git", "directory": "packages/vitest" }, - "homepage": "https://argos-ci.com/docs/vitest", + "homepage": "https://argos-ci.com/docs", "bugs": { "url": "https://github.com/argos-ci/argos-javascript/issues" }, diff --git a/packages/webdriverio/README.md b/packages/webdriverio/README.md index c91c6de8..0a068075 100644 --- a/packages/webdriverio/README.md +++ b/packages/webdriverio/README.md @@ -1,20 +1,55 @@ -_Argos is a visual testing solution that fits in your workflow to avoid visual regression. Takes screenshots on each commit and be notified if something changes._ +The open source visual testing platform for AI-native engineering teams.
-# Official Argos WebdriverIO SDK +# Official Argos WebdriverIO integration [](https://www.npmjs.com/package/@argos-ci/webdriverio) [](https://www.npmjs.com/package/@argos-ci/webdriverio) [](https://www.npmjs.com/package/@argos-ci/webdriverio) -Visit [argos-ci.com/docs/webdriverio](https://argos-ci.com/docs/webdriverio) for guides, API and more. +Capture stable Argos screenshots from your [WebdriverIO](https://webdriver.io) tests. + +Visit the [WebdriverIO SDK documentation](https://argos-ci.com/docs/sdks-reference/webdriverio) for guides, the API reference, and more. + +## Installation + +Install the SDK alongside the [Argos CLI](https://argos-ci.com/docs/sdks-reference/argos-command-line-interface-cli), which uploads the screenshots to Argos: + +```sh +npm install --save-dev @argos-ci/webdriverio @argos-ci/cli +``` + +## Usage + +Use `argosScreenshot` to stabilize the UI and capture a screenshot: + +```ts +import { argosScreenshot } from "@argos-ci/webdriverio"; + +describe("Homepage", () => { + it("takes a screenshot", async () => { + await browser.url("http://localhost:3000"); + await argosScreenshot(browser, "homepage"); + }); +}); +``` + +Screenshots are saved locally (in `./screenshots/argos` by default). Upload them to Argos with the Argos CLI, usually at the end of your CI job: + +```sh +npx @argos-ci/cli upload ./screenshots +``` ## Links -- [Official SDK Docs](https://argos-ci.com/docs/) +- [Official SDK Docs](https://argos-ci.com/docs/sdks-reference/webdriverio) +- [Quickstart](https://argos-ci.com/docs/quickstart/webdriverio-quickstart) - [Discord](https://argos-ci.com/discord) diff --git a/packages/webdriverio/docs/index.mdx b/packages/webdriverio/docs/index.mdx deleted file mode 100644 index 966ab17e..00000000 --- a/packages/webdriverio/docs/index.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: WebdriverIO -slug: /webdriverio ---- - -# Argos WebdriverIO SDK - -Integrating Argos with your [WebdriverIO](https://webdriver.io) tests to enable visual testing on your application. - -## Get started - -Please refer to our [Quickstart guide](/quickstart/webdriverio) to get started with Argos and WebdriverIO. - -## API Overview - -### argosScreenshot(browser, name[, options]) - -- `browser` - A `WebdriverIO.Browser` instance -- `name` - The screenshot name; must be unique. If ends by `.png` we treat it as a path. -- `options` - Options -- `options.mask` - Specify ares that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF (customized by `maskColor`) that completely covers its bounding box. -- `options.maskColor` - Specify the color of the overlay box for masked elements, in CSS color format. Default color is pink #FF00FF. - -## Additional Resources - -- [Quickstart with Argos + WebdriverIO](/quickstart/webdriverio) -- [@argos-ci/webdriverio on GitHub](https://github.com/argos-ci/argos-javascript/tree/main/packages/webdriverio) -- [@argos-ci/webdriverio on npm](https://www.npmjs.com/package/@argos-ci/webdriverio) diff --git a/packages/webdriverio/package.json b/packages/webdriverio/package.json index fb979c0c..9d52499f 100644 --- a/packages/webdriverio/package.json +++ b/packages/webdriverio/package.json @@ -9,7 +9,7 @@ "url": "https://github.com/argos-ci/argos-javascript.git", "directory": "packages/webdriverio" }, - "homepage": "https://argos-ci.com/docs/webdriverio", + "homepage": "https://argos-ci.com/docs/sdks-reference/webdriverio", "bugs": { "url": "https://github.com/argos-ci/argos-javascript/issues" },