TestHelper.ts

// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.

import * as path from 'node:path';
import type * as child_process from 'node:child_process';

import {
  FileSystem,
  Executable,
  JsonFile,
  type FileSystemStats,
  type JsonObject
} from '@rushstack/node-core-library';
import type { ITerminal } from '@rushstack/terminal';

/**
 * Helper class for running integration tests with Rush package managers
 */
export class TestHelper {
  private readonly _rushBinPath: string;
  private readonly _terminal: ITerminal;

  public constructor(terminal: ITerminal) {
    this._terminal = terminal;
    // Resolve rush bin path from @microsoft/rush dependency
    this._rushBinPath = require.resolve('@microsoft/rush/lib/start-dev');
  }

  /**
   * Execute a Rush command using the locally-built Rush
   */
  public async executeRushAsync(
    args: string[],
    workingDirectory: string,
    environment?: NodeJS.ProcessEnv
  ): Promise<void> {
    this._terminal.writeLine(`Executing: ${process.argv0} ${this._rushBinPath} ${args.join(' ')}`);

    const childProcess: child_process.ChildProcess = Executable.spawn(
      process.argv0,
      [this._rushBinPath, ...args],
      {
        currentWorkingDirectory: workingDirectory,
        environment,
        stdio: 'inherit'
      }
    );

    await Executable.waitForExitAsync(childProcess, {
      throwOnNonZeroExitCode: true
    });
  }

  /**
   * Create a test Rush repository with the specified package manager
   */
  public async createTestRepoAsync(
    testRepoPath: string,
    packageManagerType: 'npm' | 'pnpm' | 'yarn',
    packageManagerVersion: string
  ): Promise<void> {
    // Clean up previous test run and create empty test repo directory
    this._terminal.writeLine(`Creating test repository at ${testRepoPath}...`);
    await FileSystem.ensureEmptyFolderAsync(testRepoPath);

    // Initialize Rush repo
    this._terminal.writeLine('Initializing Rush repo...');
    await this.executeRushAsync(['init'], testRepoPath);

    // Configure rush.json for the specified package manager
    this._terminal.writeLine(`Configuring rush.json for ${packageManagerType} mode...`);
    const rushJsonPath: string = path.join(testRepoPath, 'rush.json');
    const rushJson: JsonObject = await JsonFile.loadAsync(rushJsonPath);

    // Update package manager configuration
    if (packageManagerType === 'npm') {
      delete rushJson.pnpmVersion;
      delete rushJson.yarnVersion;
      rushJson.npmVersion = packageManagerVersion;
    } else if (packageManagerType === 'pnpm') {
      delete rushJson.npmVersion;
      delete rushJson.yarnVersion;
      rushJson.pnpmVersion = packageManagerVersion;
    } else if (packageManagerType === 'yarn') {
      delete rushJson.pnpmVersion;
      delete rushJson.npmVersion;
      rushJson.yarnVersion = packageManagerVersion;
    }

    // Add test projects
    rushJson.projects = [
      {
        packageName: 'test-project-a',
        projectFolder: 'projects/test-project-a'
      },
      {
        packageName: 'test-project-b',
        projectFolder: 'projects/test-project-b'
      }
    ];

    // Update nodeSupportedVersionRange to match current environment
    rushJson.nodeSupportedVersionRange = '>=18.0.0';

    await JsonFile.saveAsync(rushJson, rushJsonPath, { updateExistingFile: true });
  }

  /**
   * Create a test project with the specified configuration
   */
  public async createTestProjectAsync(
    testRepoPath: string,
    projectName: string,
    version: string,
    dependencies: Record<string, string>,
    buildScript: string
  ): Promise<void> {
    const projectPath: string = path.join(testRepoPath, 'projects', projectName);
    await FileSystem.ensureFolderAsync(projectPath);

    const packageJson: JsonObject = {
      name: projectName,
      version: version,
      main: 'lib/index.js',
      scripts: {
        build: buildScript
      },
      dependencies: dependencies
    };

    await JsonFile.saveAsync(packageJson, path.join(projectPath, 'package.json'));
  }

  /**
   * Verify that temp project tarballs were created
   */
  public async verifyTempTarballsAsync(testRepoPath: string, projectNames: string[]): Promise<void> {
    this._terminal.writeLine('\nVerifying temp project tarballs were created...');
    for (const projectName of projectNames) {
      const tarballPath: string = path.join(testRepoPath, 'common/temp/projects', `${projectName}.tgz`);
      if (!(await FileSystem.existsAsync(tarballPath))) {
        throw new Error(`ERROR: ${projectName}.tgz was not created!`);
      }
    }
    this._terminal.writeLine('✓ Temp project tarballs created successfully');
  }

  /**
   * Verify that dependencies are installed correctly
   */
  public async verifyDependenciesAsync(
    testRepoPath: string,
    projectName: string,
    expectedDependencies: string[]
  ): Promise<void> {
    this._terminal.writeLine('\nVerifying node_modules structure...');
    const projectPath: string = path.join(testRepoPath, 'projects', projectName);
    const projectNodeModules: string = path.join(projectPath, 'node_modules');

    for (const dep of expectedDependencies) {
      const depPath: string = path.join(projectNodeModules, dep);
      if (!(await FileSystem.existsAsync(depPath))) {
        throw new Error(`ERROR: ${dep} not found in ${projectName}!`);
      }

      // Verify symlinks resolve correctly for local dependencies
      if (dep.startsWith('test-project-')) {
        const depRealPath: string = await FileSystem.getRealPathAsync(depPath);
        const expectedPath: string = path.join(testRepoPath, 'projects', dep);
        const expectedRealPath: string = await FileSystem.getRealPathAsync(expectedPath);
        if (!(await this._doPathsReferToSameObjectAsync(depPath, expectedPath))) {
          throw new Error(
            `ERROR: Symlink for ${dep} does not resolve correctly!\n` +
              `Expected: ${expectedRealPath}\n` +
              `Actual: ${depRealPath}`
          );
        }
      }
    }
    this._terminal.writeLine('✓ Dependencies installed correctly');
  }

  private async _doPathsReferToSameObjectAsync(path1: string, path2: string): Promise<boolean> {
    const path1Stats: FileSystemStats = await FileSystem.getStatisticsAsync(path1);
    const path2Stats: FileSystemStats = await FileSystem.getStatisticsAsync(path2);
    return path1Stats.dev === path2Stats.dev && path1Stats.ino === path2Stats.ino;
  }

  /**
   * Verify that PNPM's global virtual store was enabled and moved out of the workspace node_modules folder.
   */
  public async verifyPnpmGlobalVirtualStoreAsync(
    testRepoPath: string,
    sharedStorePath: string
  ): Promise<void> {
    this._terminal.writeLine('\nVerifying PNPM global virtual store structure...');

    const workspaceFilePath: string = path.join(testRepoPath, 'common/temp/pnpm-workspace.yaml');
    const workspaceFileContents: string = await FileSystem.readFileAsync(workspaceFilePath);
    if (!workspaceFileContents.includes('enableGlobalVirtualStore: true')) {
      throw new Error(`ERROR: enableGlobalVirtualStore was not written to ${workspaceFilePath}`);
    }

    const localVirtualStorePath: string = path.join(testRepoPath, 'common/temp/node_modules/.pnpm');
    if (await FileSystem.existsAsync(localVirtualStorePath)) {
      const localVirtualStoreItemNames: string[] =
        await FileSystem.readFolderItemNamesAsync(localVirtualStorePath);
      const unexpectedLocalPackageFolders: string[] = localVirtualStoreItemNames.filter(
        (itemName) => itemName !== 'lock.yaml' && itemName !== 'node_modules'
      );
      if (unexpectedLocalPackageFolders.length > 0) {
        throw new Error(
          `ERROR: Expected ${localVirtualStorePath} to omit package instance folders, but found: ` +
            unexpectedLocalPackageFolders.join(', ')
        );
      }
    }

    if (!(await FileSystem.existsAsync(sharedStorePath))) {
      throw new Error(`ERROR: Shared PNPM store was not created at ${sharedStorePath}`);
    }

    const sharedStoreItemNames: string[] = await FileSystem.readFolderItemNamesAsync(sharedStorePath);
    if (sharedStoreItemNames.length === 0) {
      throw new Error(`ERROR: Shared PNPM store is empty at ${sharedStorePath}`);
    }

    const globalVirtualStorePath: string = await this._findPnpmGlobalVirtualStorePathAsync(sharedStorePath);
    if (!(await FileSystem.existsAsync(globalVirtualStorePath))) {
      throw new Error(
        `ERROR: Expected PNPM global virtual store package links under ${sharedStorePath}, ` +
          `but ${globalVirtualStorePath} was not found.`
      );
    }

    const globalVirtualStoreItemNames: string[] =
      await FileSystem.readFolderItemNamesAsync(globalVirtualStorePath);
    if (globalVirtualStoreItemNames.length === 0) {
      throw new Error(
        `ERROR: PNPM global virtual store package links folder is empty at ${globalVirtualStorePath}`
      );
    }

    this._terminal.writeLine('✓ PNPM global virtual store structure verified');
  }

  private async _findPnpmGlobalVirtualStorePathAsync(sharedStorePath: string): Promise<string> {
    const sharedStoreVersionFolderNames: string[] =
      await FileSystem.readFolderItemNamesAsync(sharedStorePath);
    for (const folderName of sharedStoreVersionFolderNames) {
      if (folderName.startsWith('v')) {
        const linksPath: string = path.join(sharedStorePath, folderName, 'links');
        if (await FileSystem.existsAsync(linksPath)) {
          return linksPath;
        }
      }
    }

    return path.join(sharedStorePath, '<version>', 'links');
  }

  /**
   * Verify that build outputs were created
   */
  public async verifyBuildOutputsAsync(testRepoPath: string, projectNames: string[]): Promise<void> {
    this._terminal.writeLine('\nVerifying build outputs...');
    for (const projectName of projectNames) {
      const outputPath: string = path.join(testRepoPath, 'projects', projectName, 'lib/index.js');
      if (!(await FileSystem.existsAsync(outputPath))) {
        throw new Error(`ERROR: ${projectName} build output not found!`);
      }
    }
    this._terminal.writeLine('✓ Build completed successfully');
  }

  /**
   * Test that the built code executes correctly
   */
  public async testBuiltCodeAsync(testRepoPath: string, projectName: string): Promise<void> {
    this._terminal.writeLine('\nTesting built code...');
    const projectLib: string = path.join(testRepoPath, 'projects', projectName, 'lib/index.js');

    // Use forward slashes for require() path on all platforms
    const projectLibPosix: string = projectLib.split(path.sep).join(path.posix.sep);

    // Use Executable.spawnSync to capture output
    const result: string = Executable.spawnSync(
      process.argv0,
      ['-e', `const b = require('${projectLibPosix}'); console.log(b.test());`],
      {
        currentWorkingDirectory: testRepoPath
      }
    ).stdout.toString();

    if (!result.includes('Using: Hello from A')) {
      throw new Error('ERROR: Built code did not execute as expected!');
    }
    this._terminal.writeLine('✓ Built code executes correctly');
  }
}