@hs-web-team/eslint-config-node 3.2.0-next.5 → 3.2.0-next.7

package/CLAUDE.md

@@ -94,6 +94,7 @@ When testing changes to this package in downstream projects, you'll typically:
   - 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
@@ -111,7 +112,7 @@ When testing changes to this package in downstream projects, you'll typically:
   - 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` - Cypress 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

package/README.md

@@ -115,43 +115,13 @@ For detailed Stylelint configuration documentation, see [examples/stylelint-usag
 
 This package provides shared Cypress configuration for E2E testing.
 
-1. Install dependencies
+1. Install Cypress
 
     ```sh
-    npm i -D cypress @badeball/cypress-cucumber-preprocessor esbuild js-yaml
-    ```
-
-2. Create `cypress.config.js` in project root
-
-    ```javascript
-    const { defineConfig } = require('cypress');
-    const { config, envs, getBaseUrls } = require('@hs-web-team/eslint-config-node/cypress.config');
-
-    module.exports = defineConfig({
-      ...config,
-      e2e: {
-        ...config.e2e,
-        baseUrl: 'http://localhost:3000',
-      },
-      env: {
-        ...envs,
-      },
-    });
-    ```
-
-3. Add scripts to package.json
-
-    ```json
-    {
-      "scripts": {
-        "cypress:open": "cypress open",
-        "cypress:run": "cypress run",
-        "test:e2e": "cypress run"
-      }
-    }
+    npm i -D cypress@15
     ```
 
-For detailed Cypress configuration documentation including HubSpot-specific features, see [examples/cypress-usage.md](./examples/cypress-usage.md).
+For detailed Cypress configuration and migration documentation, see [examples/cypress-usage.md](./examples/cypress-usage.md).
 
 ## Where to use it
 

package/cypress.config.cjs

@@ -127,4 +127,5 @@ module.exports = {
   envs,
   getDevBaseUrl,
   getBaseUrls,
+  setupNodeEvents,
 };

package/cypress.config.d.ts

@@ -0,0 +1,18 @@
+/// <reference types="cypress" />
+
+export declare const envs: {
+  currentEnv: string;
+  DEV: string;
+  QA: string;
+  PROD: string;
+};
+
+export declare const config: Cypress.ConfigOptions;
+
+export declare function setupNodeEvents(
+  on: Cypress.PluginEvents,
+  config: Cypress.PluginConfigOptions
+): Promise<Cypress.PluginConfigOptions>;
+
+export declare function getDevBaseUrl(): string | null;
+export declare function getBaseUrls(): Record<string, string | null> | null;

package/examples/cypress-usage.md

@@ -4,16 +4,10 @@ This package provides a shared Cypress configuration for E2E testing in HubSpot
 
 ## Installation
 
-1. Install the package and Cypress dependencies:
+For full setup instructions, see the [Cypress Framework Setup](https://git.hubteam.com/pages/MarketingWebTeam/webteam-docs/docs/developers/coding-on-the-web-team/software-testing/cypress-framework-setup/) guide.
 
 ```bash
-npm install --save-dev @hs-web-team/eslint-config-node cypress @badeball/cypress-cucumber-preprocessor esbuild js-yaml
-```
-
-2. If using TypeScript:
-
-```bash
-npm install --save-dev typescript @types/node
+npm i -D cypress@15
 ```
 
 ## Usage
@@ -24,18 +18,13 @@ Create a `cypress.config.js` file in your project root:
 
 ```javascript
 const { defineConfig } = require('cypress');
-const { config, envs, getBaseUrls } = require('@hs-web-team/eslint-config-node/cypress.config');
+const { config } = require('@hs-web-team/eslint-config-node/cypress.config');
 
 module.exports = defineConfig({
   ...config,
   e2e: {
     ...config.e2e,
-    baseUrl: 'http://localhost:3000', // Your app's base URL
-    // Add custom e2e options here
-  },
-  env: {
-    ...envs,
-    // Add custom environment variables
+    baseUrl: 'http://localhost:3000',
   },
 });
 ```
@@ -54,7 +43,7 @@ module.exports = defineConfig({
   ...config,
   e2e: {
     ...config.e2e,
-    baseUrl: baseUrls.qa || baseUrls.DEV, // Use QA or DEV environment
+    baseUrl: baseUrls.qa,
   },
   env: {
     ...envs,
@@ -67,173 +56,84 @@ module.exports = defineConfig({
 
 ### Core Configuration
 
-The shared configuration includes:
-
-- **Chrome Web Security**: Disabled (`chromeWebSecurity: false`) for cross-origin testing
-- **Timeouts**:
-  - Default command timeout: 20 seconds
-  - Page load timeout: 20 seconds
-  - Response timeout: 20 seconds
-- **Test Settings**:
-  - Port: 3500
-  - Viewport: 1920x1080
-  - Tests kept in memory: 0 (prevents memory issues)
-- **Retries**:
-  - Run mode: 1 retry
-  - Open mode: 0 retries
-- **Screenshots**: Enabled on failure
+- **Chrome Web Security**: Disabled for cross-origin testing
+- **Timeouts**: 20s for default command, page load, and response (Cypress default is 4s)
+- **Viewport**: 1920x1080
+- **Retries**: 1 in run mode, 0 in open mode
 - **Video**: Disabled by default
-- **Trash assets before runs**: Enabled
+- **Tests kept in memory**: 0 (prevents memory issues)
 
 ### E2E Configuration
 
-- **Spec Pattern**: `cypress/e2e/*.cy.js`
-- **Cucumber Support**: Includes Cucumber preprocessor setup with esbuild
-- **TypeScript Support**: Native TypeScript support via esbuild (no additional loader needed)
-- **esbuild Preprocessor**: Fast bundling for `.feature` files, TypeScript, and JavaScript
+- **Spec pattern**: `cypress/e2e/*.cy.js`
+- **Cucumber support**: Includes Cucumber preprocessor setup with esbuild
+- **TypeScript support**: Native via esbuild, no additional loader needed
 
-### Environment Utilities
+### Exports
 
-The configuration exports utility functions:
+| Export | Description |
+|--------|-------------|
+| `config` | Main Cypress configuration object |
+| `envs` | Environment constants (`DEV`, `QA`, `PROD`, `currentEnv`) |
+| `setupNodeEvents` | The `setupNodeEvents` function (for custom extension) |
+| `getDevBaseUrl()` | Reads `baseUrl` from the DEV portal in `hubspot.config.yml` |
+| `getBaseUrls()` | Reads URLs for all environments from `.ci/config.yml` |
 
 #### `envs`
-Pre-configured environment constants:
+
 ```javascript
-const envs = {
-  currentEnv: 'qa', // Default environment
+{
+  currentEnv: 'qa',
   DEV: 'DEV',
   QA: 'qa',
   PROD: 'prod',
-};
+}
 ```
 
 #### `getDevBaseUrl()`
-Retrieves the `baseUrl` from the `DEV` portal in `hubspot.config.yml`:
 
-```javascript
-const devUrl = getDevBaseUrl(); // Returns baseUrl or null
-```
+Returns the `baseUrl` from the `DEV` portal in `hubspot.config.yml`, or `null` if not found.
 
-**Requirements**:
-- Project must have a `hubspot.config.yml` file
-- DEV portal must have a `baseUrl` property configured
+**Requirements**: `hubspot.config.yml` must exist and the DEV portal must have a `baseUrl` property.
 
 #### `getBaseUrls()`
-Retrieves base URLs for all environments from `.ci/config.yml`:
+
+Returns base URLs for all environments:
 
 ```javascript
-const urls = getBaseUrls();
 // Returns: { DEV: '...', qa: '...', prod: '...' }
 ```
 
-**Requirements**:
-- `.ci/config.yml` file with `regression.e2eTestEnvironment` configuration
-- Format:
-  ```yaml
-  regression:
-    e2eTestEnvironment:
-      - name: qa
-        url: https://qa.example.com
-      - name: prod
-        url: https://prod.example.com
-  ```
-
-## Project Structure
-
-### Recommended Folder Structure
-
-```
-project-root/
-├── cypress/
-│   ├── e2e/
-│   │   ├── login.cy.js
-│   │   └── homepage.cy.js
-│   ├── fixtures/
-│   │   └── users.json
-│   ├── support/
-│   │   ├── commands.js
-│   │   └── e2e.js
-│   └── downloads/
-├── cypress.config.js
-└── package.json
-```
-
-### For Cucumber/BDD Testing
+The `DEV` key comes from `getDevBaseUrl()`. The `qa` and `prod` keys come from `.ci/config.yml`:
 
+```yaml
+regression:
+  e2eTestEnvironment:
+    - name: qa
+      url: https://qa.example.com
+    - name: prod
+      url: https://prod.example.com
 ```
-project-root/
-├── cypress/
-│   ├── e2e/
-│   │   └── features/
-│   │       ├── login.feature
-│   │       └── homepage.feature
-│   ├── support/
-│   │   ├── step_definitions/
-│   │   │   ├── login.ts
-│   │   │   └── homepage.ts
-│   │   └── e2e.ts
-└── cypress.config.js
-```
-
-## Add Scripts to package.json
-
-Add Cypress scripts to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "cypress:open": "cypress open",
-    "cypress:run": "cypress run",
-    "cypress:run:chrome": "cypress run --browser chrome",
-    "cypress:run:headed": "cypress run --headed",
-    "test:e2e": "cypress run"
-  }
-}
-```
-
-Then run:
-- `npm run cypress:open` - Open Cypress Test Runner (interactive)
-- `npm run cypress:run` - Run all tests headlessly
-- `npm run test:e2e` - Run E2E tests (alias for cypress:run)
 
 ## Customizing Configuration
 
-### Override Default Values
+### Add Custom setupNodeEvents
 
-```javascript
-const { defineConfig } = require('cypress');
-const { config } = require('@hs-web-team/eslint-config-node/cypress.config');
+`setupNodeEvents` is embedded in `config.e2e`. If you override it without calling the package's version, you'll lose the Cucumber preprocessor and esbuild setup.
 
-module.exports = defineConfig({
-  ...config,
-  // Override specific values
-  defaultCommandTimeout: 30000,
-  viewportWidth: 1280,
-  viewportHeight: 720,
-  video: true, // Enable video recording
-  e2e: {
-    ...config.e2e,
-    baseUrl: 'http://localhost:8080',
-    specPattern: 'cypress/integration/**/*.spec.js',
-  },
-});
-```
-
-### Add Custom setupNodeEvents
+Import `setupNodeEvents` directly and call it first:
 
 ```javascript
 const { defineConfig } = require('cypress');
-const { config } = require('@hs-web-team/eslint-config-node/cypress.config');
+const { config, setupNodeEvents: wtSetupNodeEvents } = require('@hs-web-team/eslint-config-node/cypress.config');
 
 module.exports = defineConfig({
   ...config,
   e2e: {
     ...config.e2e,
-    async setupNodeEvents(on, cypressConfig) {
-      // Call shared setup first (includes esbuild preprocessor and Cucumber setup)
-      const updatedConfig = await config.e2e.setupNodeEvents(on, cypressConfig);
+    async setupNodeEvents(on, cfg) {
+      await wtSetupNodeEvents(on, cfg);
 
-      // Add your custom tasks/events
       on('task', {
         log(message) {
           console.log(message);
@@ -241,137 +141,117 @@ module.exports = defineConfig({
         },
       });
 
-      return updatedConfig;
+      return cfg;
     },
   },
 });
 ```
 
-## Integration with CI/CD
-
-### GitHub Actions Example
+If you don't need custom node events, omit `setupNodeEvents` entirely and just spread `...config.e2e`.
 
-```yaml
-name: E2E Tests
-on: [push, pull_request]
-
-jobs:
-  cypress-run:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run Cypress tests
-        uses: cypress-io/github-action@v6
-        with:
-          start: npm start
-          wait-on: 'http://localhost:3000'
-```
+## Migrating from `@hs-web-team/eslint-config-browser`
 
-## TypeScript Support
+### 1. Update the import
 
-The configuration includes TypeScript support. Create a `tsconfig.json` for Cypress:
+**JavaScript:**
+```javascript
+// Before
+const { getDevBaseUrl, getBaseUrls, config, envs } = require('@hs-web-team/eslint-config-browser/cypress.config.js');
 
-```json
-{
-  "compilerOptions": {
-    "target": "ES2021",
-    "lib": ["ES2021", "DOM"],
-    "types": ["cypress", "node"],
-    "moduleResolution": "node",
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "strict": true
-  },
-  "include": ["cypress/**/*.ts"],
-  "exclude": ["node_modules"]
-}
+// After
+const { getDevBaseUrl, getBaseUrls, config, envs } = require('@hs-web-team/eslint-config-node/cypress.config');
 ```
 
-## Cucumber/BDD Support
+**TypeScript (module format stays the same — ESM `import`/`export default` still works):**
+```typescript
+// Before
+import { getDevBaseUrl, getBaseUrls, config, envs } from '@hs-web-team/eslint-config-browser/cypress.config.js';
 
-The configuration includes Cucumber preprocessor setup. To use it:
-
-1. Install dependencies:
-```bash
-npm install --save-dev @badeball/cypress-cucumber-preprocessor
+// After
+import { getDevBaseUrl, getBaseUrls, envs, config as wtConfig } from '@hs-web-team/eslint-config-node/cypress.config';
 ```
 
-2. Create `.cypress-cucumber-preprocessorrc.json`:
-```json
-{
-  "stepDefinitions": "cypress/support/step_definitions/**/*.{js,ts}",
-  "json": {
-    "enabled": true,
-    "output": "cypress/results/cucumber-report.json"
-  }
-}
-```
-
-3. Write feature files in `cypress/e2e/features/`:
-```gherkin
-Feature: Login
-
-  Scenario: User can login successfully
-    Given I visit the login page
-    When I enter valid credentials
-    Then I should see the dashboard
-```
+### 2. Remove manual `setupNodeEvents`
 
-## Cypress Version Requirements
+Cucumber and esbuild are bundled into `config.e2e.setupNodeEvents`. Remove your manual `setupNodeEvents` function entirely and spread `...config.e2e` to inherit it automatically.
 
-This configuration requires **Cypress 14.0.0 or higher**. Cypress 14+ includes:
+If you need to add custom tasks on top, see [Add Custom setupNodeEvents](#add-custom-setupnodeevents).
 
-- Improved performance for component test runs
-- Support for latest React, Angular, Next.js, Svelte, and Vite versions
-- Seamless handling of Chrome's document.domain deprecation
-- Upgraded Electron with Chromium 130+ for enhanced stability
-- Better `cy.origin()` support for cross-subdomain navigation
+### 3. Update the config structure
 
-Current latest version: Cypress 15.9.0 (January 2026)
+The old pattern built the full `e2e` object from scratch — repeating settings already in the bundle — then assigned it:
 
-## Why esbuild Instead of Webpack?
+```javascript
+const customConfig = { ...config };
+const e2e = {
+  specPattern: 'cypress/e2e/**/*.feature',
+  baseUrl,
+  setupNodeEvents, // manual webpack + cucumber setup
+  defaultCommandTimeout: 20000, // already in bundle
+  retries: { runMode: 1, openMode: 0 }, // already in bundle
+  // ...
+};
+customConfig.e2e = e2e;
+module.exports = defineConfig(customConfig);
+```
 
-The configuration uses **esbuild** instead of webpack for several reasons:
+The new pattern spreads `...config.e2e` to inherit bundled settings (including `setupNodeEvents`) and only adds project-specific overrides:
 
-- ⚡ **Much faster** - esbuild is 10-100x faster than webpack
-- 🎯 **Native TypeScript support** - No need for ts-loader or additional configuration
-- 📦 **Smaller footprint** - Fewer dependencies to install and maintain
-- 🔧 **Simpler setup** - Works out of the box with the Cucumber preprocessor
+**JavaScript:**
+```javascript
+module.exports = defineConfig({
+  ...config,
+  e2e: {
+    ...config.e2e,
+    specPattern: 'cypress/e2e/**/*.feature',
+    baseUrl,
+    supportFile: 'cypress/support/e2e.js',
+    reporter: 'mochawesome',
+    reporterOptions: {
+      reportDir: 'cypress/results',
+      overwrite: false,
+      html: true,
+      json: true,
+    },
+  },
+});
+```
 
-## Troubleshooting
+**TypeScript:**
+```typescript
+export default defineConfig({
+  e2e: {
+    ...wtConfig.e2e,
+    specPattern: 'cypress/e2e/**/*.feature',
+    baseUrl,
+    supportFile: 'cypress/support/e2e.ts',
+    reporter: 'mochawesome',
+    reporterOptions: {
+      reportDir: 'cypress/results',
+      overwrite: false,
+      html: true,
+      json: true,
+    },
+  },
+  blockHosts: '*.google-analytics.com',
+});
+```
 
-### Module Not Found Errors
+### 4. Keep project-specific settings not in the bundle
 
-Ensure all required dependencies are installed:
-```bash
-npm install --save-dev cypress @badeball/cypress-cucumber-preprocessor esbuild js-yaml
-```
+These are not included in the bundle and must be carried over manually if your project uses them:
 
-### Compilation Errors
+- `reporter` and `reporterOptions` (e.g. mochawesome)
+- `supportFile`
+- `blockHosts`
+- `fixturesFolder`, `screenshotsFolder`, `videosFolder`
+- `testIsolation`
+- `specPattern` (if using `.feature` files — bundle default is `cypress/e2e/*.cy.js`)
 
-If you see compilation errors with TypeScript files, ensure esbuild is installed:
-```bash
-npm install --save-dev esbuild
-```
+## Troubleshooting
 
 ### Environment Configuration Not Loading
 
 Ensure your project has the required configuration files:
 - `hubspot.config.yml` for HubSpot projects
 - `.ci/config.yml` for multi-environment setups
-
-### Memory Issues
-
-The configuration sets `numTestsKeptInMemory: 0` to prevent memory issues. If you still experience problems, consider:
-- Running tests in smaller batches
-- Increasing Node.js memory: `NODE_OPTIONS=--max_old_space_size=4096 cypress run`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hs-web-team/eslint-config-node",
-  "version": "3.2.0-next.5",
+  "version": "3.2.0-next.7",
   "description": "HubSpot Marketing WebTeam shared configurations for ESLint, Prettier, Stylelint, and Cypress",
   "main": "index.js",
   "type": "module",
@@ -9,7 +9,17 @@
     "./browser": "./browser.js",
     "./.prettierrc.json": "./.prettierrc.json",
     "./.stylelintrc.json": "./.stylelintrc.json",
-    "./cypress.config": "./cypress.config.cjs"
+    "./cypress.config": {
+      "types": "./cypress.config.d.ts",
+      "require": "./cypress.config.cjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "cypress.config": [
+        "./cypress.config.d.ts"
+      ]
+    }
   },
   "scripts": {
     "lint": "npx eslint -c ./index.js *.js --fix",

package/cypress.config.ts

@@ -1,120 +0,0 @@
-import yaml from 'js-yaml';
-import fs from 'fs';
-import path from 'path';
-import createBundler from '@bahmutov/cypress-esbuild-preprocessor';
-import { addCucumberPreprocessorPlugin } from '@badeball/cypress-cucumber-preprocessor';
-import { createEsbuildPlugin } from '@badeball/cypress-cucumber-preprocessor/esbuild';
-
-const DEV = 'DEV';
-const QA = 'qa';
-const PROD = 'prod';
-const currentEnv = QA;
-
-export 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: string): string => {
-  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.
- */
-export const getDevBaseUrl = (): string | null => {
-  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 fileContents = fs.readFileSync(configPath, 'utf8');
-    const { portals } = yaml.load(fileContents) as { portals: Array<{ name: string; baseUrl?: string }> };
-    const devPortal = portals.find(portal => portal.name === 'DEV');
-    return devPortal?.baseUrl || 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
- */
-export const getBaseUrls = (): Record<string, string | null> | null => {
-  let fileContents = '';
-  let ciConfig: { regression?: { e2eTestEnvironment?: Array<{ name: string; url: string }> } } = {};
-  const baseUrls: Record<string, string | null> = {};
-  baseUrls[envs.DEV] = getDevBaseUrl();
-
-  const fileExist = fs.existsSync('.ci/config.yml');
-  if (fileExist) {
-    fileContents = fs.readFileSync('.ci/config.yml', 'utf8');
-    ciConfig = yaml.load(fileContents) as typeof ciConfig;
-    if (ciConfig.regression?.e2eTestEnvironment && ciConfig.regression.e2eTestEnvironment.length > 0) {
-      try {
-        ciConfig.regression.e2eTestEnvironment.forEach(item => {
-          baseUrls[item.name] = 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: Cypress.PluginEvents,
-  config: Cypress.PluginConfigOptions,
-): Promise<Cypress.PluginConfigOptions> {
-  await addCucumberPreprocessorPlugin(on, config);
-  on(
-    'file:preprocessor',
-    createBundler({ plugins: [createEsbuildPlugin(config)] }),
-  );
-  return config;
-}
-
-const e2e: Cypress.EndToEndConfigOptions = {
-  specPattern: 'cypress/e2e/*.cy.js',
-  setupNodeEvents,
-};
-
-export const config: Cypress.ConfigOptions = {
-  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,
-};