Merge pull request #26 from HubSpotWebTeam/feature/add-cypress-configuration

Feature/add cypress configuration

Author: darkmavis1980

.github/workflows/main.yml

@@ -11,11 +11,11 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [22, 24]
+        node: [24]
 
     name: Node ${{ matrix.node }} lint
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Run unit tests
         uses: actions/setup-node@v6
         with:

.github/workflows/pr.yml

@@ -11,11 +11,11 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [22, 24]
+        node: [24]
 
     name: Node ${{ matrix.node }} sample
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Run unit tests
         uses: actions/setup-node@v6
         with:

.nvmrc

@@ -1 +1 @@
-v22
+v24

.stylelintrc.json

@@ -0,0 +1,40 @@
+{
+  "extends": "stylelint-config-standard-scss",
+  "rules": {
+    "length-zero-no-unit": null,
+    "declaration-empty-line-before": null,
+    "no-empty-source": null,
+    "at-rule-no-unknown": [
+      true,
+      {
+        "ignoreAtRules": ["function", "if", "else", "for", "each", "include", "mixin", "extend"]
+      }
+    ],
+    "scss/dollar-variable-pattern": null,
+    "scss/at-import-no-partial-leading-underscore": null,
+    "selector-class-pattern": null,
+    "declaration-block-no-redundant-longhand-properties": null,
+    "scss/at-import-partial-extension": null,
+    "alpha-value-notation": null,
+    "scss/percent-placeholder-pattern": null,
+    "scss/at-mixin-argumentless-call-parentheses": null,
+    "color-function-notation": null,
+    "scss/dollar-variable-empty-line-before": null,
+    "shorthand-property-no-redundant-values": null,
+    "no-duplicate-selectors": null,
+    "scss/double-slash-comment-whitespace-inside": null,
+    "font-family-name-quotes": null,
+    "media-feature-range-notation": [
+      "context",
+      {
+        "severity": "warning"
+      }
+    ],
+    "value-keyword-case": [
+      "lower",
+      {
+        "camelCaseSvgKeywords": true
+      }
+    ]
+  }
+}

CLAUDE.md

@@ -4,7 +4,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Overview
 
-This is an ESLint configuration package (`@hs-web-team/eslint-config-node`) for HubSpot Marketing WebTeam projects. It provides shared ESLint rules and Prettier configuration for both backend Node.js projects and browser/React applications.
+This is a configuration package (`@hs-web-team/eslint-config-node`) for HubSpot Marketing WebTeam projects. It provides shared configurations for:
+- **ESLint** rules for Node.js and browser/React projects
+- **Prettier** formatting configuration
+- **Stylelint** rules for SCSS/CSS linting
+- **Cypress** E2E testing configuration
 
 ## Key Commands
 
@@ -66,27 +70,76 @@ When testing changes to this package in downstream projects, you'll typically:
   - Arrow parens: avoid, LF line endings, single attribute per line
   - Override for YAML files: uses double quotes instead of single
 
+### Stylelint Configuration
+- **`.stylelintrc.json`**: Shared Stylelint configuration for SCSS/CSS linting
+  - Extends `stylelint-config-standard-scss` for standard SCSS linting rules
+  - Customized rules for HubSpot projects:
+    - Disables strict class name patterns and variable naming patterns
+    - Allows zero units (e.g., `0px`), redundant longhand properties, and duplicate selectors
+    - Configures SCSS-specific rules to ignore common directives (`@function`, `@if`, `@mixin`, etc.)
+    - Enforces lowercase keywords with camelCase for SVG keywords
+    - Sets media feature range notation to "context" with warning severity
+  - Consuming projects extend this via `.stylelintrc.json`: `{ "extends": "@hs-web-team/eslint-config-node/.stylelintrc.json" }`
+  - Documentation: `examples/stylelint-usage.md`
+
+### Cypress Configuration
+- **`cypress.config.cjs`**: Shared Cypress configuration for E2E testing
+  - Uses CommonJS (`require`) syntax
+  - Core settings:
+    - Disables Chrome web security for cross-origin testing
+    - Timeouts: 20s default command, page load, and response timeouts
+    - Viewport: 1920x1080
+    - Retries: 1 retry in run mode, 0 in open mode
+    - Screenshots on failure enabled, video disabled by default
+  - Uses **esbuild** preprocessor for fast bundling (much faster than webpack)
+  - Includes Cucumber preprocessor setup with native esbuild support
+  - Native TypeScript support via esbuild (no additional loader needed)
+  - `@badeball/cypress-cucumber-preprocessor`, `@bahmutov/cypress-esbuild-preprocessor`, `esbuild`, and `js-yaml` are all bundled — consumers only need to install `cypress`
+  - Spec pattern: `cypress/e2e/*.cy.js`
+  - Exported utilities:
+    - `config`: Main Cypress configuration object
+    - `envs`: Environment constants (DEV, QA, PROD)
+    - `getDevBaseUrl()`: Reads baseUrl from `hubspot.config.yml` DEV portal
+    - `getBaseUrls()`: Reads URLs from `.ci/config.yml` for multiple environments
+  - HubSpot-specific: Designed to work with HubSpot CMS projects using `hubspot.config.yml`
+  - Documentation: `examples/cypress-usage.md`
+
 ### Package Details
 - **Type**: ESM module (`"type": "module"`)
-- **Node requirement**: >= 22
+- **Node requirement**: >= 24
 - **Exports**:
-  - Main export (`.`): `index.js` - Node.js configuration
-  - Browser export (`./browser`): `browser.js` - Browser/React configuration
+  - Main export (`.`): `index.js` - Node.js ESLint configuration
+  - Browser export (`./browser`): `browser.js` - Browser/React ESLint configuration
+  - Prettier export (`./.prettierrc.json`): `.prettierrc.json` - Prettier configuration
+  - Stylelint export (`./.stylelintrc.json`): `.stylelintrc.json` - Stylelint configuration
+  - Cypress export (`./cypress.config`): `cypress.config.cjs` (runtime), `cypress.config.d.ts` (types)
 - **Binary command**: `add-prettier` maps to `bin/add-prettier-scripts.js`
 
 ### Migration Context
 This package is currently on v3, which uses ESLint 9's flat config format. The project has migrated from:
 - v1 → v2: See `docs/MIGRATION-V2.md`
-- v2 → v3: See `docs/MIGRATION-V3.md` (ESLint 9 flat config migration requiring Node.js 22+)
+- v2 → v3: See `docs/MIGRATION-V3.md` (ESLint 9 flat config migration requiring Node.js 24+)
 
 ## Important Notes
 
-- This package supports both **backend Node.js projects** (default export) and **browser/React projects** (`/browser` export)
-- The configuration uses ESLint 9's flat config format (not the legacy `.eslintrc` format)
-- Downstream projects extend this config in their `eslint.config.js` by spreading the imported config:
-  - Node.js: `...wtConfig`
-  - Browser: `...wtBrowserConfig`
-- Mixed module systems: `bin/add-prettier-scripts.js` uses CommonJS (`require`) while the main package is ESM
-- CI runs on Node 22 and 24 (see `.github/workflows/pr.yml`)
+- This package supports multiple use cases:
+  - **ESLint**: Backend Node.js projects (default export) and browser/React projects (`/browser` export)
+  - **Prettier**: Code formatting (`./.prettierrc.json` export)
+  - **Stylelint**: SCSS/CSS linting (`./.stylelintrc.json` export)
+  - **Cypress**: E2E testing (`./cypress.config` export)
+- ESLint configuration uses ESLint 9's flat config format (not the legacy `.eslintrc` format)
+- Downstream projects extend configs:
+  - ESLint (Node.js): `...wtConfig` in `eslint.config.js`
+  - ESLint (Browser): `...wtBrowserConfig` in `eslint.config.js`
+  - Prettier: Import via `.prettierrc.js` using `require('@hs-web-team/eslint-config-node/.prettierrc.json')`
+  - Stylelint: Extend in `.stylelintrc.json` with `"extends": "@hs-web-team/eslint-config-node/.stylelintrc.json"`
+  - Cypress: Import and spread in `cypress.config.js`
+- Mixed module systems:
+  - Main package is ESM (`index.js`, `browser.js`)
+  - Utility scripts use CommonJS (`bin/add-prettier-scripts.js`, `cypress.config.cjs`)
+- CI runs on Node 24 (see `.github/workflows/pr.yml`)
 - No automated tests currently (`npm test` will fail with "Error: no test specified")
-- Detailed browser configuration documentation available in `examples/browser-usage.md`
+- Detailed documentation available in `examples/`:
+  - `browser-usage.md` - Browser/React ESLint configuration
+  - `stylelint-usage.md` - Stylelint configuration
+  - `cypress-usage.md` - Cypress E2E testing configuration

README.md

@@ -8,6 +8,8 @@ This package provides ESLint rules and configurations for **Hubspot Marketing We
 
 - [Node.js Setup](#nodejs-setup)
 - [Browser/React Setup](#browserreact-setup)
+- [Stylelint Setup](#stylelint-setup)
+- [Cypress Setup](#cypress-setup)
 - [Where to use it](#where-to-use-it)
 - [Using the Prettier Scripts](#using-the-prettier-scripts)
 <!-- index-end -->
@@ -78,14 +80,60 @@ This package provides ESLint rules and configurations for **Hubspot Marketing We
 
 For detailed browser configuration documentation and migration guides, see [examples/browser-usage.md](./examples/browser-usage.md).
 
+## Stylelint Setup
+
+This package provides shared Stylelint configuration for SCSS/CSS linting.
+
+1. Install dependencies
+
+    ```sh
+    npm i -D stylelint stylelint-config-standard-scss
+    ```
+
+2. Create `.stylelintrc.json` in project root
+
+    ```json
+    {
+      "extends": "@hs-web-team/eslint-config-node/.stylelintrc.json"
+    }
+    ```
+
+3. Add scripts to package.json
+
+    ```json
+    {
+      "scripts": {
+        "stylelint:check": "stylelint '**/*.{css,scss}'",
+        "stylelint:fix": "stylelint '**/*.{css,scss}' --fix"
+      }
+    }
+    ```
+
+For detailed Stylelint configuration documentation, see [examples/stylelint-usage.md](./examples/stylelint-usage.md).
+
+## Cypress Setup
+
+This package provides shared Cypress configuration for E2E testing.
+
+1. Install Cypress
+
+    ```sh
+    npm i -D cypress@15
+    ```
+
+For detailed Cypress configuration and migration documentation, see [examples/cypress-usage.md](./examples/cypress-usage.md).
+
 ## Where to use it
 
-This package provides two configurations:
+This package provides multiple configurations:
 
 - **Node.js configuration** (default export): For backend Node.js projects
 - **Browser configuration** (`/browser` export): For browser-based projects including React applications
+- **Stylelint configuration** (`.stylelintrc.json` export): For SCSS/CSS linting
+- **Cypress configuration** (`cypress.config` export): For E2E testing with Cypress
+- **Prettier configuration** (`.prettierrc.json` export): For code formatting
 
-Choose the appropriate configuration based on your project type.
+Choose the appropriate configurations based on your project needs.
 
 ## Using the Prettier Scripts
 
@@ -115,4 +163,4 @@ See [MIGRATION-V2.md](./docs/MIGRATION-V2.md)
 
 ## Migration from v2 to v3
 
-See [MIGRATION-V3.md](./docs/MIGRATION-V3.md)
+See [MIGRATION-V3.md](./docs/MIGRATION-V3.md)

cypress.config.cjs

@@ -0,0 +1,131 @@
+const yaml = require('js-yaml');
+const fs = require('fs');
+const path = require('path');
+const createBundler = require('@bahmutov/cypress-esbuild-preprocessor');
+const { addCucumberPreprocessorPlugin } = require('@badeball/cypress-cucumber-preprocessor');
+const { createEsbuildPlugin } = require('@badeball/cypress-cucumber-preprocessor/esbuild');
+
+const DEV = 'DEV';
+const QA = 'qa';
+const PROD = 'prod';
+const currentEnv = QA;
+
+const envs = {
+  currentEnv,
+  DEV,
+  QA,
+  PROD,
+};
+
+/**
+ * @description Recursively climbs up the filepath, until it finds what directory
+ * the directory where the hubspot.config.yml file is located.
+ *
+ * @param {string} currDir - the current working directory path to search from
+ * @returns {string} The absolute path of the project's root directory
+ */
+const getRootDir = currDir => {
+  if (fs.existsSync(path.join(currDir, 'hubspot.config.yml'))) return currDir;
+  const parentDir = path.dirname(currDir);
+  if (parentDir === currDir) {
+    throw new Error('Error: Could not find the hubspot.config.yml file within the projects directories.');
+  }
+  return getRootDir(parentDir);
+};
+
+/**
+ * @returns {string|null} The `baseUrl` set for the `DEV` portal in `hubspot.config.yml`
+ *   or `null` if this is not the dev environment or no such property exists.
+ */
+const getDevBaseUrl = () => {
+  try {
+    global.console.log(
+      'To test a dev URL, add the `baseUrl` property to your `DEV` portal configuration in `hubspot.config.yml`',
+    );
+
+    const root = getRootDir(__dirname);
+    const configPath = path.resolve(root, 'hubspot.config.yml');
+    const config = fs.readFileSync(configPath, 'utf8');
+    const { portals } = yaml.load(config);
+    const devPortal = portals.find(portal => portal.name === 'DEV');
+    const devBaseUrl = devPortal.baseUrl;
+    return devBaseUrl || null;
+  } catch (error) {
+    global.console.error(error);
+    return null;
+  }
+};
+
+/**
+ * @description Get the baseUrls for different environments from the ci config file for local test execution.
+ * @returns {object} baseUrls - The base urls object
+ */
+const getBaseUrls = () => {
+  let fileContents = '';
+  let ciConfig = {};
+  const baseUrls = {};
+  baseUrls[envs.DEV] = getDevBaseUrl();
+
+  const fileExist = fs.existsSync('.ci/config.yml');
+  if (fileExist) {
+    fileContents = fs.readFileSync('.ci/config.yml', 'utf8');
+    ciConfig = yaml.load(fileContents);
+    if (ciConfig.regression.e2eTestEnvironment && ciConfig.regression.e2eTestEnvironment.length > 0) {
+      try {
+        ciConfig.regression.e2eTestEnvironment.forEach(item => {
+          const envName = item.name;
+          baseUrls[envName] = item.url;
+        });
+      } catch (error) {
+        console.error('Error reading the base urls from the ci config file:', error);
+        return null;
+      }
+    }
+  }
+  return baseUrls || null;
+};
+
+async function setupNodeEvents(on, config) {
+  // This is required for the preprocessor to be able to generate JSON reports after each run
+  await addCucumberPreprocessorPlugin(on, config);
+
+  // Use esbuild for fast TypeScript and feature file processing
+  on(
+    'file:preprocessor',
+    createBundler({ plugins: [createEsbuildPlugin(config)] }),
+  );
+
+  return config;
+}
+
+const e2e = {
+  specPattern: 'cypress/e2e/*.cy.js',
+  setupNodeEvents,
+};
+
+const config = {
+  chromeWebSecurity: false,
+  defaultCommandTimeout: 20000,
+  e2e,
+  numTestsKeptInMemory: 0,
+  pageLoadTimeout: 20000,
+  port: 3500,
+  responseTimeout: 20000,
+  retries: {
+    runMode: 1,
+    openMode: 0,
+  },
+  screenshotOnRunFailure: true,
+  trashAssetsBeforeRuns: true,
+  video: false,
+  viewportHeight: 1080,
+  viewportWidth: 1920,
+};
+
+module.exports = {
+  config,
+  envs,
+  getDevBaseUrl,
+  getBaseUrls,
+  setupNodeEvents,
+};