temp-cli-and-templates-and-readme

Signed-off-by: Francesco Torchia <[email protected]>

Author: torchiaf

.eslintignore

@@ -28,4 +28,5 @@ kubewarden-ui/
 styleguide/src/stories/Example/
 storybook/src/stories/Example/
 cypress/dist/
-cypress/bin/cypress.js
+cypress/bin/
+cypress/template/

.gitignore

@@ -91,6 +91,7 @@ sw.*
 cypress/videos
 cypress/screenshots
 cypress/accessibility
+browser-logs
 setupTestEnv.sh
 
 # Storybook

cypress.config.ts

@@ -1,4 +1,4 @@
-// Import and use the base configuration from @rancher/cypress package
+// Import and use the base configuration from cypress package
 import baseConfig from './cypress/base-config';
 
 export default baseConfig;

cypress/README.md

@@ -5,19 +5,101 @@ Reusable Cypress E2E test utilities, page objects, and support files for Rancher
 ## Installation
 
 ```bash
-npm install @rancher/cypress
+npm install @rancher/cypress --save-dev
 # or
-yarn add @rancher/cypress
+yarn add @rancher/cypress --dev
 ```
 
-## What's Included
+## Setup
 
 This package provides:
 
-- **Page Objects** (`/po/*`) - Reusable page object models for common UI components and pages
-- **Blueprints** (`/blueprints/*`) - Test fixtures and data blueprints
+- **E2E Tests** (`/e2e/*`) - Predefined Cypress tests for common Rancher Dashboard scenarios
+- **Page Objects** (`/e2e/po/*`) - Reusable page object models for common Rancher UI components and pages
+- **Blueprints** (`/e2e/blueprints/*`) - Test fixtures and data blueprints
 - **Support Files** (`/support/*`) - Custom Cypress commands and utilities
-- **Configuration** (`/config/*`) - Base Cypress configuration
+- **Cypress Configuration** (`/base-config`) - Base Cypress configuration
+- **Extendable Config** (`/extend-config`) - Utilities to extend Cypress config
+
+### Using @rancher/cypress CLI
+
+#### Available Commands
+
+| Command                        | Description                                      |
+|--------------------------------|--------------------------------------------------|
+| npx rancher-cypress open      | Launch Cypress UI                                |
+| npx rancher-cypress run       | Run Cypress tests                                |
+| npx rancher-cypress init      | Scaffold a Cypress project structure             |
+
+#### What does `init` do?
+
+The `init` command will:
+
+- Create a new `cypress/` directory in your project (if one does not already exist)
+- Copy all template files and folders into `cypress/`
+- Copy `cypress.config.ts` into your project root (not inside `cypress/`)
+- Abort if a `cypress/` directory or `cypress.config.ts` already exists, to avoid overwriting your work
+
+This provides a ready-to-use Cypress project structure for Rancher Dashboard E2E testing.
+
+---
+
+### Manual Setup
+
+#### Cypress Configuration
+
+Create a `cypress.config.ts` file in your consuming project:
+
+Use default base configuration:
+
+```typescript
+import baseConfig from '@rancher/cypress/base-config';
+
+export default baseConfig;
+```
+
+Or extend the base configuration:
+
+```typescript
+import { extendConfig } from '@rancher/cypress/extend-config';
+
+export default extendConfig({
+  env: {
+    yourCustomEnvVar: 'value',
+  },
+  e2e: {
+    specPattern:                  yourCustomSpecPattern
+  }
+});
+```
+
+#### Package.json
+
+Add new tasks to Cypress configuration in `package.json`:
+
+```json
+{
+  "cypress": {
+    "tasks": {
+      "cypress:open": "npx rancher-cypress open --e2e --browser chrome",
+      "cypress:run": "npx rancher-cypress run",
+    }
+  }
+}
+```
+
+#### TypeScript Configuration
+
+> **Important:**
+> To enable type completion for custom Cypress commands and page objects, add `"cypress"` to the `types` array in your root `tsconfig.json`:
+>
+> ```json
+> {
+>   "compilerOptions": {
+>     "types": ["cypress"]
+>   }
+> }
+> ```
 
 ## Usage
 
@@ -54,33 +136,47 @@ This will load all custom Cypress commands like:
 ### Using Blueprints (Fixtures)
 
 ```typescript
-cy.fixture('@rancher/cypress/blueprints/my-fixture.json').then((data) => {
+cy.fixture('@rancher/cypress/blueprints/fixture.json').then((data) => {
   // use fixture data
 });
 ```
 
-### Using Base Configuration
-
-In your project's `cypress.config.ts`:
-
-```typescript
-import { getBaseConfig } from '@rancher/cypress/config/base.config';
-
-const baseConfig = getBaseConfig();
-
-export default {
-  ...baseConfig,
-  e2e: {
-    ...baseConfig.e2e,
-    specPattern: 'your-tests/**/*.spec.ts',
-    // override any other settings
-  }
-};
-```
+## Implementation & Publishing Notes
+
+### Project Structure & Build Process
+- All source files (e2e, support, base-config.ts, extend-config.ts, globals.d.ts) are copied into a temporary `tmp/` directory before build.
+- The build script (`build.sh`) normalizes internal imports and compiles TypeScript from `tmp/` to `dist/` using `tsconfig.build.json`.
+- After compilation, TypeScript source files are also copied to `dist/` for better developer experience.
+- Non-TypeScript assets (README, package.json, etc.) are copied to `dist/` for publishing.
+- The published npm package only includes the `dist/` directory, as specified in `package.json`.
+
+### TypeScript Configuration
+- `tsconfig.build.json` extends the main `tsconfig.json` but restricts compilation to `tmp/**/*` and outputs only to `dist/`.
+- Source maps and declaration maps are generated for easier debugging and type navigation.
+
+### Clean Build Guarantee
+- Only the files actually referenced by the cypress code are included in the build, keeping the package minimal.
+
+### Publishing
+- To manual publish, run:
+  ```bash
+  npm run build
+  cd dist
+  npm publish
+  ```
+- To automate publishing, use the provided GitHub Actions workflow.
+  Add a new release tag, and the workflow will build and publish the package to npm.
+  ```bash
+  git tag cypress-pkg-v1.0.0
+  git push upstream cypress-pkg-v1.0.0
+  ```
+
+### Troubleshooting
+- If you see build errors not shown in VS Code, ensure you are using the same TypeScript config (`tsconfig.build.json`) for both build and editor, or manually run `npx tsc --project tsconfig.build.json` to check.
+- If you see stray build artifacts in dependency directories, check the build script and tsconfig paths to ensure all compilation is isolated to `tmp/` and `dist/`.
 
 ## Requirements
 
-- Cypress 11.1.0
 - Node.js >= 20.0.0
 - TypeScript >= 5.0.0
 

cypress/bin/cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('child_process');
+
+const [, , cmd, ...args] = process.argv;
+
+function showHelp() {
+  console.log(`\n@rancher/cypress CLI\n\nUsage:\n  npx rancher-cypress <command> [args]\n\nCommands:\n  open         Launch Cypress UI\n  run          Run Cypress tests\n  init         Scaffold Cypress project structure\n\nExamples:\n  npx rancher-cypress open\n  npx rancher-cypress run\n  npx rancher-cypress init\n`);
+}
+
+if (!cmd) {
+  showHelp();
+  process.exit(0);
+}
+
+if (cmd === 'init') {
+  require('./init');
+} else {
+  // Try to resolve cypress binary in the consuming project
+  let cypressBin;
+
+  try {
+    cypressBin = require.resolve('./node_modules/.bin/cypress', { paths: [process.cwd()] });
+  } catch (e) {
+    console.error('\nERROR: Cypress is not installed in this project.\nPlease install it with:\n  npm install cypress --save-dev\n');
+    process.exit(1);
+  }
+  const result = spawnSync(cypressBin, [cmd, ...args], { stdio: 'inherit' });
+
+  process.exit(result.status);
+}

cypress/bin/init.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+
+function copyTemplateFiles(templateDir, targetDir) {
+  if (!fs.existsSync(templateDir)) {
+    console.error(`Template directory not found: ${ templateDir }`);
+    process.exit(1);
+  }
+  fs.copySync(templateDir, targetDir, {
+    overwrite:    false,
+    errorOnExist: true,
+    filter:       (src) => {
+      // Skip node_modules and .DS_Store
+      const rel = path.relative(templateDir, src);
+
+      return !rel.includes('node_modules') && !rel.endsWith('.DS_Store');
+    }
+  });
+}
+
+function main() {
+  const cwd = process.cwd();
+  const templateDir = path.join(__dirname, '../template');
+  const targetCypressDir = path.join(cwd, 'cypress');
+  const rootConfigFile = path.join(cwd, 'cypress.config.ts');
+
+  if (fs.existsSync(targetCypressDir)) {
+    console.error('🚫 A cypress/ directory already exists in this project. Aborting.');
+    process.exit(1);
+  }
+  if (fs.existsSync(rootConfigFile)) {
+    console.error('🚫 A cypress.config.ts already exists in this project root. Aborting.');
+    process.exit(1);
+  }
+
+  console.log(`Scaffolding Cypress project structure in: ${ targetCypressDir }`);
+  try {
+    fs.ensureDirSync(targetCypressDir);
+
+    // Copy all template files except cypress.config.ts into cypress/
+    copyTemplateFiles(templateDir, targetCypressDir);
+
+    // Copy cypress.config.ts to root if it exists in template
+    const templateConfigFile = path.join(templateDir, 'cypress.config.ts');
+
+    if (fs.existsSync(templateConfigFile)) {
+      fs.copyFileSync(templateConfigFile, rootConfigFile);
+    }
+
+    // Remove cypress.config.ts from cypress/
+    const copiedConfig = path.join(targetCypressDir, 'cypress.config.ts');
+
+    if (fs.existsSync(copiedConfig)) {
+      fs.removeSync(copiedConfig);
+    }
+
+    // Add Cypress scripts to package.json
+    const pkgJsonPath = path.join(cwd, 'package.json');
+
+    if (fs.existsSync(pkgJsonPath)) {
+      try {
+        const pkg = fs.readJsonSync(pkgJsonPath);
+
+        pkg.scripts = pkg.scripts || {};
+        let changed = false;
+
+        if (!pkg.scripts['cypress:open']) {
+          pkg.scripts['cypress:open'] = 'rancher-cypress open --e2e --browser chrome';
+          changed = true;
+        }
+        if (!pkg.scripts['cypress:run']) {
+          pkg.scripts['cypress:run'] = 'rancher-cypress run';
+          changed = true;
+        }
+        if (changed) {
+          fs.writeJsonSync(pkgJsonPath, pkg, { spaces: 2 });
+          console.log('  Added cypress:open and/or cypress:run scripts to package.json');
+        } else {
+          console.log('ℹ  cypress:open and cypress:run scripts already exist in package.json');
+        }
+      } catch (e) {
+        console.error('❌ Could not update package.json with Cypress scripts:', e);
+      }
+    } else {
+      console.warn('⚠️  No package.json found in project root. Skipping script addition.');
+    }
+
+    // Add or create tsconfig.json with "cypress" in types
+    const tsConfigPath = path.join(cwd, 'tsconfig.json');
+    if (fs.existsSync(tsConfigPath)) {
+      try {
+        const tsConfig = fs.readJsonSync(tsConfigPath);
+        tsConfig.compilerOptions = tsConfig.compilerOptions || {};
+        let types = tsConfig.compilerOptions.types || [];
+        if (!Array.isArray(types)) types = [types];
+        if (!types.includes('cypress')) {
+          types.push('cypress');
+          tsConfig.compilerOptions.types = types;
+          fs.writeJsonSync(tsConfigPath, tsConfig, { spaces: 2 });
+          console.log('  Added "cypress" to compilerOptions.types in tsconfig.json');
+        } else {
+          console.log('  "cypress" already present in compilerOptions.types in tsconfig.json');
+        }
+      } catch (e) {
+        console.error('❌ Could not update tsconfig.json:', e);
+      }
+    } else {
+      // Create a basic tsconfig.json
+      const basicTsConfig = {
+        compilerOptions: {
+          target: "esnext",
+          module: "commonjs",
+          types: ["cypress"]
+        }
+      };
+      try {
+        fs.writeJsonSync(tsConfigPath, basicTsConfig, { spaces: 2 });
+        console.log('Created basic tsconfig.json with "cypress" in types');
+      } catch (e) {
+        console.error('❌ Could not create tsconfig.json:', e);
+      }
+    }
+
+    console.log('✅ Cypress project structure created in ./cypress');
+    console.log('Next steps:');
+    console.log('  Edit cypress.config.ts as needed');
+    console.log('  Run "yarn cypress:open" to launch Cypress');
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      console.error('🚫 Some files already exist. Aborting to avoid overwrite.');
+    } else {
+      console.error('❌ Error copying template files:', err);
+    }
+    process.exit(1);
+  }
+}
+
+main();

cypress/build.sh

@@ -65,6 +65,10 @@ cp README.md dist/
 cp .npmignore dist/
 cp globals.d.ts dist/
 
+# Copy CLI and template for yarn link testing
+cp -r bin dist/
+cp -r template dist/
+
 echo "Package built successfully in dist/ directory"
 echo "To test with yarn link:"
 echo "  cd dist"