create-appraise 0.1.0

package/templates/default/src/tests/utils/cache.util.ts

@@ -0,0 +1,260 @@
+import { readFileSync } from 'fs'
+import { globSync } from 'glob'
+import { LocatorCollection, LocatorMap } from '@/types/locator/locator.type'
+import * as path from 'path'
+
+/**
+ * Singleton cache for managing Playwright locator collections
+ *
+ * This class provides a lazy-loading cache for locator JSON files. It automatically
+ * discovers all locator files in the configured directory and loads them on-demand
+ * to optimize memory usage and startup time.
+ *
+ * Features:
+ * - Singleton pattern ensures single instance across the application
+ * - Lazy loading of locator files for better performance
+ * - Automatic file discovery using glob patterns
+ * - Error handling for malformed JSON files
+ * - Memory-efficient with optional preloading
+ */
+export class LocatorCache {
+  /** Singleton instance of the LocatorCache */
+  private static instance: LocatorCache
+
+  /** In-memory cache of loaded locator collections, keyed by file name */
+  private data: Record<string, LocatorCollection> = {}
+
+  /** Map of file names to their full file paths */
+  private filePaths: Record<string, string> = {}
+
+  /** Set of file names that have been loaded into memory */
+  private loadedFiles: Set<string> = new Set()
+
+  /**
+   * Private constructor for singleton pattern
+   *
+   * Automatically discovers all JSON files in the locator directory and
+   * maps them by their base filename for easy lookup.
+   *
+   * @private
+   */
+  private constructor() {
+    globSync(`${process.env.LOCATOR_LOCATION ?? 'src/tests/locators'}/**/*.json`).forEach(file => {
+      const fileName = path.basename(file, path.extname(file))
+      this.filePaths[fileName ?? file] = file
+    })
+  }
+
+  /**
+   * Gets the singleton instance of LocatorCache
+   *
+   * Creates a new instance if one doesn't exist, otherwise returns the existing instance.
+   *
+   * @returns The singleton LocatorCache instance
+   *
+   * @example
+   * ```typescript
+   * const cache = LocatorCache.getInstance();
+   * const locators = cache.get('home');
+   * ```
+   */
+  public static getInstance(): LocatorCache {
+    if (!LocatorCache.instance) {
+      LocatorCache.instance = new LocatorCache()
+    }
+    return LocatorCache.instance
+  }
+
+  /**
+   * Retrieves a locator collection by key (filename without extension)
+   *
+   * Performs lazy loading - the file is only loaded from disk when first requested.
+   * Returns a shallow copy of the data to prevent external modifications.
+   *
+   * @param key - The filename (without .json extension) of the locator file
+   * @returns A shallow copy of the LocatorCollection, or null if not found or error
+   *
+   * @example
+   * ```typescript
+   * const homeLocators = cache.get('home');
+   * if (homeLocators) {
+   *   console.log(homeLocators.loginButton); // '#login-btn'
+   * }
+   * ```
+   */
+  public get(key: string) {
+    // Lazy load the file if not already loaded
+    if (!this.loadedFiles.has(key) && this.filePaths[key]) {
+      try {
+        const filePath = this.filePaths[key]
+        const data = JSON.parse(readFileSync(filePath, 'utf8'))
+        this.data[key] = data as LocatorCollection
+        this.loadedFiles.add(key)
+      } catch (error) {
+        console.error(`Error loading locator file for key "${key}":`, error)
+        return null
+      }
+    }
+
+    return this.data[key] ? { ...this.data[key] } : null
+  }
+
+  /**
+   * Preloads all locator files into memory at once
+   *
+   * This method loads all discovered locator files into memory, which can be
+   * useful for ensuring all files are available upfront or for performance
+   * optimization when you know all locators will be needed.
+   *
+   * @example
+   * ```typescript
+   * const cache = LocatorCache.getInstance();
+   * cache.preloadAll(); // Load all locator files now
+   * ```
+   */
+  public preloadAll(): void {
+    Object.keys(this.filePaths).forEach(key => {
+      if (!this.loadedFiles.has(key)) {
+        this.get(key) // This will trigger lazy loading
+      }
+    })
+  }
+
+  /**
+   * Gets all available locator file keys without loading the files
+   *
+   * Returns the list of all discovered locator file names (without extensions)
+   * that are available for loading. This is useful for listing available
+   * locator collections or for validation purposes.
+   *
+   * @returns Array of available locator file names
+   *
+   * @example
+   * ```typescript
+   * const cache = LocatorCache.getInstance();
+   * const availableKeys = cache.getAvailableKeys();
+   * console.log('Available locators:', availableKeys); // ['home', 'login', 'dashboard']
+   * ```
+   */
+  public getAvailableKeys(): string[] {
+    return Object.keys(this.filePaths)
+  }
+
+  /**
+   * Checks if a specific locator file has been loaded into memory
+   *
+   * @param key - The filename (without .json extension) to check
+   * @returns True if the file is loaded in memory, false otherwise
+   *
+   * @example
+   * ```typescript
+   * const cache = LocatorCache.getInstance();
+   * if (!cache.isLoaded('home')) {
+   *   console.log('Home locators not yet loaded');
+   * }
+   * ```
+   */
+  public isLoaded(key: string): boolean {
+    return this.loadedFiles.has(key)
+  }
+}
+
+/**
+ * Singleton cache for managing locator path mappings
+ *
+ * This class provides a cache for the locator mapping configuration that
+ * maps URL paths to their corresponding locator collection names. It loads
+ * the mapping file once at initialization and provides fast lookups.
+ *
+ * Features:
+ * - Singleton pattern ensures single instance across the application
+ * - Loads mapping configuration at initialization
+ * - Provides fast path-to-locator-name lookups
+ * - Error handling for malformed mapping files
+ */
+export class LocatorMapCache {
+  /** Singleton instance of the LocatorMapCache */
+  private static instance: LocatorMapCache
+
+  /** Array of locator mappings loaded from the configuration file */
+  private data: LocatorMap[] = []
+
+  /**
+   * Private constructor for singleton pattern
+   *
+   * Loads the locator mapping configuration file at initialization.
+   * The mapping file contains path-to-locator-name mappings.
+   *
+   * @private
+   */
+  private constructor() {
+    this.data = JSON.parse(
+      readFileSync(process.env.LOCATOR_MAP_LOCATION ?? 'src/tests/mapping/locator-map.json', 'utf8'),
+    )
+  }
+
+  /**
+   * Gets the singleton instance of LocatorMapCache
+   *
+   * Creates a new instance if one doesn't exist, otherwise returns the existing instance.
+   *
+   * @returns The singleton LocatorMapCache instance
+   *
+   * @example
+   * ```typescript
+   * const mapCache = LocatorMapCache.getInstance();
+   * const mapping = mapCache.get('/login');
+   * ```
+   */
+  public static getInstance(): LocatorMapCache {
+    if (!LocatorMapCache.instance) {
+      LocatorMapCache.instance = new LocatorMapCache()
+    }
+    return LocatorMapCache.instance
+  }
+
+  /**
+   * Retrieves a locator mapping by URL path
+   *
+   * Searches through the loaded mappings to find the one that matches the given path.
+   * Returns a default empty mapping if not found or on error.
+   *
+   * @param key - The URL path to look up (e.g., '/login', '/dashboard')
+   * @returns The LocatorMap object containing the path and corresponding locator name
+   *
+   * @example
+   * ```typescript
+   * const mapping = mapCache.get('/login');
+   * console.log(mapping.name); // 'login'
+   * console.log(mapping.path); // '/login'
+   * ```
+   */
+  public get(key: string): LocatorMap {
+    try {
+      return this.data.find(map => map.path === key) as LocatorMap
+    } catch (error) {
+      console.error(error)
+      return {
+        name: '',
+        path: '',
+      }
+    }
+  }
+
+  /**
+   * Retrieves all locator mappings
+   *
+   * @returns Array of all LocatorMap objects
+   *
+   * @example
+   * ```typescript
+   * const allMappings = mapCache.getAll();
+   * allMappings.forEach(mapping => {
+   *   console.log(`${mapping.path} -> ${mapping.name}`);
+   * });
+   * ```
+   */
+  public getAll(): LocatorMap[] {
+    return this.data
+  }
+}

package/templates/default/src/tests/utils/cli.util.ts

@@ -0,0 +1,177 @@
+import { Command, Option, OptionValues } from 'commander'
+import { getAllEnvironments } from './environment.util.js'
+import parseTagExpression from '@cucumber/tag-expressions'
+
+/**
+ * Configuration options for the CLI tool
+ * @extends OptionValues - Extends Commander.js OptionValues for CLI integration
+ */
+export interface CliOptions extends OptionValues {
+  /** The target environment to run tests against */
+  environment: string
+  /** Cucumber tag expression to filter test scenarios */
+  tags: string
+  /** Number of parallel workers to run tests with */
+  parallel: number
+  /** Browser engine to use for test execution */
+  browser: 'chromium' | 'firefox' | 'webkit'
+  /** Whether to run browser in headless mode */
+  headless: 'true' | 'false'
+}
+
+/** Available browser choices for test execution */
+const BROWSER_CHOICES = ['chromium', 'firefox', 'webkit'] as const
+
+/** Available headless mode choices */
+const HEADLESS_CHOICES = ['true', 'false'] as const
+
+/** Default number of parallel workers */
+const DEFAULT_PARALLEL_WORKERS = 1
+
+/** Default browser engine */
+const DEFAULT_BROWSER = 'chromium'
+
+/** Default headless mode setting */
+const DEFAULT_HEADLESS = 'true'
+
+/**
+ * Commander.js program instance for CLI argument parsing
+ * Configured with all available options and validation rules
+ */
+const program = new Command()
+
+/**
+ * Available environment names loaded from configuration
+ * Used to validate the --environment option
+ */
+let environmentNames: string[] = []
+try {
+  environmentNames = Object.keys(getAllEnvironments())
+  if (environmentNames.length === 0) {
+    console.warn('⚠️  No environments found in configuration')
+  }
+} catch (error) {
+  console.error('❌ Failed to load environments:', error instanceof Error ? error.message : 'Unknown error')
+  process.exit(1)
+}
+
+/**
+ * Validates and parses a positive integer value from command line input
+ *
+ * Used as a custom parser for the --parallel option to ensure only valid
+ * positive integers are accepted.
+ *
+ * @param val - The string value to parse from command line
+ * @returns The parsed positive integer
+ * @throws Error if the value is not a valid positive integer
+ *
+ * @example
+ * ```typescript
+ * parsePositiveInt("4") // Returns 4
+ * parsePositiveInt("0") // Throws Error
+ * parsePositiveInt("abc") // Throws Error
+ * ```
+ */
+function parsePositiveInt(val: string): number {
+  const n = Number(val)
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`--parallel must be a positive integer, got "${val}"`)
+  }
+  return n
+}
+
+/**
+ * Validates a Cucumber tag expression for proper syntax
+ *
+ * Uses the @cucumber/tag-expressions library to validate that the provided
+ * tag expression follows Cucumber's tag expression syntax rules.
+ *
+ * @param val - The tag expression string to validate
+ * @returns The validated tag expression (unchanged if valid)
+ * @throws Error if the tag expression is invalid
+ *
+ * @example
+ * ```typescript
+ * validateCucumberTagExpression('@smoke') // Returns '@smoke'
+ * validateCucumberTagExpression('@smoke and @regression') // Returns '@smoke and @regression'
+ * validateCucumberTagExpression('invalid expression') // Throws Error
+ * ```
+ */
+function validateCucumberTagExpression(val: string): string {
+  try {
+    parseTagExpression(val)
+    return val
+  } catch (error) {
+    throw new Error(`Invalid tag expression: ${error instanceof Error ? error.message : 'Unknown error'}`)
+  }
+}
+
+/**
+ * Configure the Commander.js CLI program with all available options
+ *
+ * Sets up the command name, description, version, and all command line options
+ * with their respective validation rules and default values.
+ */
+program
+  .name('cucumber-cli')
+  .description('A CLI tool for running Cucumber tests with different configurations')
+  .version('1.0.0')
+  .addOption(
+    new Option('-e, --environment <environment>', 'The environment to run the tests on')
+      .choices(environmentNames)
+      .makeOptionMandatory(),
+  )
+  .addOption(
+    new Option('-t, --tags <tags>', 'The tags to run the tests on (Cucumber tag expression)')
+      .argParser(validateCucumberTagExpression)
+      .makeOptionMandatory(),
+  )
+  .option(
+    '-p, --parallel <parallel>',
+    'The number of parallel workers to run the tests on',
+    parsePositiveInt,
+    DEFAULT_PARALLEL_WORKERS,
+  )
+  .addOption(
+    new Option('-b, --browser <browser>', 'The browser to run the tests on')
+      .choices(BROWSER_CHOICES)
+      .default(DEFAULT_BROWSER),
+  )
+  .addOption(
+    new Option('-h, --headless <headless>', 'The headless mode to run the tests on')
+      .choices(HEADLESS_CHOICES)
+      .default(DEFAULT_HEADLESS),
+  )
+
+/**
+ * Starts the CLI and parses command line arguments
+ *
+ * This is the main entry point for the CLI tool. It parses command line arguments,
+ * validates them according to the configured rules, and returns the parsed options.
+ * The function handles errors gracefully and exits the process with appropriate
+ * error codes if parsing fails.
+ *
+ * @returns The parsed and validated CLI options
+ * @throws Error if parsing fails or required options are missing
+ *
+ * @example
+ * ```typescript
+ * const options = startCli();
+ * console.log(`Running tests on ${options.environment} with ${options.parallel} workers`);
+ * ```
+ */
+export function startCli(): CliOptions {
+  try {
+    program.parse()
+    const options = program.opts() as CliOptions
+
+    return options
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('❌ CLI Error:', error.message)
+    } else {
+      console.error('❌ CLI Error: Unknown error occurred')
+    }
+    process.exit(1)
+  }
+}

package/templates/default/src/tests/utils/environment.util.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from 'fs'
+
+interface EnvironmentConfig {
+  baseUrl: string
+  apiBaseUrl: string
+  email: string
+  password: string
+}
+
+/**
+ * Retrieves the configuration for a specific environment from the environments.json file
+ *
+ * This function reads the environments configuration file and returns the configuration
+ * object for the specified environment. The configuration typically contains URLs, API keys,
+ * database connections, and other environment-specific settings.
+ *
+ * @param environment - The name of the environment to retrieve configuration for
+ * @returns The environment configuration object, or undefined if environment not found
+ *
+ * @example
+ * ```typescript
+ * const devConfig = getEnvironment('development');
+ * console.log(devConfig.baseUrl); // 'https://dev.example.com'
+ *
+ * const prodConfig = getEnvironment('production');
+ * console.log(prodConfig.apiKey); // 'prod-api-key-123'
+ * ```
+ *
+ * @throws Will throw an error if the environments.json file cannot be read or parsed
+ */
+export function getEnvironment(environment: string) {
+  const environmentConfig: { [key: string]: EnvironmentConfig } = JSON.parse(
+    readFileSync(`${process.cwd()}/src/tests/config/environments/environments.json`, 'utf8'),
+  )
+  return environmentConfig[environment] as EnvironmentConfig
+}
+
+/**
+ * Retrieves all environment configurations from the environments.json file
+ *
+ * This function reads the entire environments configuration file and returns all
+ * available environment configurations. Useful for listing available environments
+ * or performing operations across all environments.
+ *
+ * @returns An object containing all environment configurations, keyed by environment name
+ *
+ * @example
+ * ```typescript
+ * const allEnvs = getAllEnvironments();
+ * console.log(Object.keys(allEnvs)); // ['development', 'staging', 'production']
+ *
+ * // Iterate through all environments
+ * Object.entries(allEnvs).forEach(([name, config]) => {
+ *   console.log(`${name}: ${config.baseUrl}`);
+ * });
+ * ```
+ *
+ * @throws Will throw an error if the environments.json file cannot be read or parsed
+ */
+export function getAllEnvironments() {
+  const environmentConfig = JSON.parse(
+    readFileSync(`${process.cwd()}/src/tests/config/environments/environments.json`, 'utf8'),
+  )
+  return environmentConfig
+}