System tests should cleanup after themselves

__tests__/__packages__/cli-test-utils/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to the Zowe CLI test utils package will be documented in this file.
 
+## Recent Changes
+
+- Updated `TestEnvironment`, `ITestEnvironment`, and `TestUtils` to simplify and automate the cleanup of test resources, such as datasets, USS files, jobs, and local files created during system tests.
+
 ## `8.0.0-next.202408271330`
 
 - BugFix: Removed obsolete V1 `profiles` property from the parameters object returned by `mockHandlerParameters` method.

__tests__/__packages__/cli-test-utils/src/environment/TestEnvironment.ts

@@ -11,11 +11,10 @@
 
 import * as fs from "fs";
 import * as nodePath from "path";
-
 import * as yaml from "js-yaml";
 import { v4 as uuidv4 } from "uuid";
-import { ImperativeError, ImperativeExpect, IO, Logger, LoggingConfigurer, TextUtils } from "@zowe/imperative";
-
+import { AbstractSession, ImperativeError, ImperativeExpect,
+    IO, Logger, LoggingConfigurer, ProfileInfo, TextUtils } from "@zowe/imperative";
 import { ISetupEnvironmentParms } from "./doc/parms/ISetupEnvironmentParms";
 import { ITestEnvironment } from "./doc/response/ITestEnvironment";
 import { TempTestProfiles } from "./TempTestProfiles";
@@ -43,7 +42,7 @@ export class TestEnvironment {
      * @returns {Promise<ITestEnvironment>}
      * @memberof TestEnvironment
      */
-    public static async setUp(params: ISetupEnvironmentParms): Promise<ITestEnvironment<any>> {
+    public static async setUp(params: ISetupEnvironmentParms, session?: AbstractSession): Promise<ITestEnvironment<any>> {
         // Validate the input parameters
         ImperativeExpect.toNotBeNullOrUndefined(params,
             `${TestEnvironment.ERROR_TAG} createTestEnv(): No parameters supplied.`);
@@ -85,6 +84,24 @@ export class TestEnvironment {
         return result;
     }
 
+    /**
+     * Create a session using the default z/OSMF profile (if a session has not been added to test)
+     * @returns {Promise<ISession>} - A promise that resolves to the created session object
+     * @throws Will throw an error if reading profiles or creating the session fails
+     * @memberof TestEnvironment
+     */
+    public static async createSession(): Promise<AbstractSession> {
+        // Load connection info from default z/OSMF profile
+        const profInfo = new ProfileInfo("zowe");
+        await profInfo.readProfilesFromDisk();
+        const zosmfProfAttrs = profInfo.getDefaultProfile("zosmf");
+        if (!zosmfProfAttrs) {
+            throw new Error("Default z/OSMF profile not found.");
+        }
+        const zosmfMergedArgs = profInfo.mergeArgsForProfile(zosmfProfAttrs, { getSecureVals: true });
+        return ProfileInfo.createSession(zosmfMergedArgs.knownArgs);
+    }
+
     /**
      * Clean up your test environment.
      * Deletes any temporary profiles that have been created

__tests__/__packages__/cli-test-utils/src/environment/doc/index.ts

@@ -10,4 +10,4 @@
 */
 
 export * from "./parms/ISetupEnvironmentParms";
-export * from "./response/ITestEnvironment";
+export * from "./response/ITestEnvironment";

__tests__/__packages__/cli-test-utils/src/environment/doc/response/ITestEnvironment.ts

@@ -14,7 +14,7 @@
  * @export
  * @interface ITestEnvironment
  */
-export interface ITestEnvironment<TestPropertiesSchema> {
+export interface ITestEnvironment<ITestPropertiesSchema> {
     /**
      * The working directory for your test environment. It is a unique (uuid) area where your tests can create
      * their home folders (for imperative, etc.) and you can use the area as scratch for any files, etc. that
@@ -29,10 +29,10 @@ export interface ITestEnvironment<TestPropertiesSchema> {
      * in the case that no system test properties were configured or could be loaded.
      *
      * Not present if skipProperties is specified on ISetupEnvironmentParms
-     * @type {TestPropertiesSchema}
+     * @type {ITestPropertiesSchema}
      * @memberof ITestEnvironment
      */
-    systemTestProperties: TestPropertiesSchema;
+    systemTestProperties: ITestPropertiesSchema;
 
     /**
      * Set of environmental variables (such as profile/logging home directory)

__tests__/__src__/TestUtils.ts

@@ -10,9 +10,83 @@
 */
 
 import { randomBytes } from "crypto";
-import { ZosFilesConstants } from "../../packages/zosfiles/src";
-import { Imperative, Headers, AbstractSession } from "@zowe/imperative";
+import * as fs from "fs";
+import { Imperative, Headers, AbstractSession, IO } from "@zowe/imperative";
 import { ZosmfRestClient } from "../../packages/core/src";
+import { ZosFilesConstants, Delete } from "../../packages/zosfiles/src";
+import { DeleteJobs, ICommonJobParms, IDeleteJobParms, IJob } from "../../packages/zosjobs/src";
+import { posix } from "path";
+import { spawnSync, SpawnSyncReturns, ExecFileException } from "child_process";
+import { ITestEnvironment } from "./environment/ITestEnvironment";
+import { promisify } from "util";
+
+/**
+ * Delete a local testing file after use
+ * @param {string} filePath - File path of temporary file
+ */
+export function deleteLocalFile(filePath: string): void {
+    try {
+        fs.unlinkSync(filePath);
+    } catch {
+        // If fs.unlinkSync fails, try to delete it with IO.deleteFile
+        try {
+            IO.deleteFile(posix.basename(filePath));
+        } catch {
+            throw new Error(`Error deleting local file: ${filePath}`);
+        }
+    }
+}
+
+/**
+ * Delete local directories after use
+ * @param {string[]} directories - Array of directories to delete
+ */
+export function deleteLocalDirectories(directories: string[]): void {
+    directories.forEach((dir) => {
+        try {
+            if (fs.existsSync(dir)) {
+                fs.rmdirSync(dir, { recursive: true });
+            }
+        } catch (err) {
+            throw new Error(`Error deleting directory: ${dir}`);
+        }
+    });
+}
+/**
+ * Delete a uss file from the mainframe
+ * @param {AbstractSession} session - z/OSMF connection info
+ * @param {string} fileName - The name of the USS file
+ */
+export function deleteFiles(session: AbstractSession, fileName: string): void {
+    Delete.ussFile(session, fileName);
+}
+
+/**
+ * Delete a dataset from the mainframe
+ * @param {AbstractSession} session - z/OSMF connection info
+ * @param {string} datasetName - The name of the dataset
+ */
+export function deleteDataset(session: AbstractSession, dataSetName: string): void {
+    Delete.dataSet(session, dataSetName);
+}
+
+/**
+ * Delete a job from the mainframe using Zowe SDKs - IJob
+ * @param {AbstractSession} session - z/OSMF connection info
+ * @param {IJob} job - the job that you want to delete
+ */
+export function deleteJob(session: AbstractSession, job: IJob): void {
+    DeleteJobs.deleteJobForJob(session, job);
+}
+
+/**
+ * Delete a job from the mainframe using Zowe SDKs - jobid, jobname
+ * @param {AbstractSession} session - z/OSMF connection info
+ * @param {params} ICommonJobParms - constains jobname and jobid for job to delete
+ */
+export function deleteJobCommon(session: AbstractSession, params: ICommonJobParms): void {
+    DeleteJobs.deleteJobCommon(session, params as IDeleteJobParms);
+}
 
 /**
  * This function strips any new lines out of the string passed.
@@ -100,11 +174,13 @@ export async function getTag(session: AbstractSession, ussPath: string) {
     return response.stdout[0];
 }
 
-export function delay(ms: number) {
-    return new Promise((resolve) => setTimeout(resolve, ms) );
-}
-
-export const delTime = 500;
+/**
+ * Pauses execution for a given number of milliseconds.
+ * @param {number} ms - Number of milliseconds to wait
+ * @returns {Promise<void>} - Resolves after the specified time has passed
+ */
+export const wait = promisify(setTimeout);
+export const waitTime = 2000; //wait 2 seconds
 
 /**
  * Use instead of `util.inspect` to get consistently formatted output that can be used in snapshots.
@@ -114,3 +190,56 @@ export const delTime = 500;
 export function inspect(obj: any) : string {
     return JSON.stringify(Object.keys(obj).reduce((newObj, key) => ({...newObj, [key]: obj[key]}), {}));
 }
+
+/**
+ * Execute a CLI script
+ * @export
+ * @param  scriptPath - the path to the script
+ * @param  testEnvironment - the test environment with env
+ * @param [args=[]] - set of script args (optional)
+ * @returns  node.js details about the results of
+ *           executing the script, including exit code and output
+ */
+export function runCliScript(scriptPath: string, testEnvironment: ITestEnvironment<any>, args: any[] = []): SpawnSyncReturns<Buffer> {
+    if (fs.existsSync(scriptPath)) {
+
+        // We force the color off to prevent any oddities in the snapshots or expected values
+        // Color can vary OS/terminal
+        const childEnv = JSON.parse(JSON.stringify(process.env));
+        childEnv.FORCE_COLOR = "0";
+        for (const key of Object.keys(testEnvironment.env)) {
+            // copy the values from the env
+            childEnv[key] = testEnvironment.env[key];
+        }
+
+        if (process.platform === "win32") {
+            // Execute the command synchronously
+            const response = spawnSync("sh", [scriptPath].concat(args), {
+                cwd: testEnvironment.workingDir,
+                encoding: "buffer",
+                env: childEnv
+            });
+            if ((response.error as ExecFileException)?.code === "ENOENT") {
+                throw new Error(`"sh" is missing from your PATH. Check that Git Bash is installed with the option to ` +
+                    `"Use Git and Unix Tools from Windows Command Prompt".`);
+            }
+            return response;
+        }
+
+        // Check to see if the file is executable
+        try {
+            fs.accessSync(scriptPath, fs.constants.X_OK);
+        } catch {
+            fs.chmodSync(scriptPath, "755");
+        }
+        return spawnSync(scriptPath, args, {
+            cwd: testEnvironment.workingDir,
+            env: childEnv,
+            encoding: "buffer"
+        });
+
+    } else {
+        throw new Error(`The script file ${scriptPath} doesn't exist`);
+
+    }
+}

__tests__/__src__/environment/ITestEnvironment.ts

@@ -0,0 +1,27 @@
+/*
+* This program and the accompanying materials are made available under the terms of the
+* Eclipse Public License v2.0 which accompanies this distribution, and is available at
+* https://www.eclipse.org/legal/epl-v20.html
+*
+* SPDX-License-Identifier: EPL-2.0
+*
+* Copyright Contributors to the Zowe Project.
+*
+*/
+
+import { ITestEnvironment as IBaseTestEnvironment } from "../../__packages__/cli-test-utils/src/environment/doc/response/ITestEnvironment";
+import { ITestEnvironmentResources } from "./ITestEnvironmentResources";
+
+/**
+ * The test environment for your test.
+ * @export
+ * @interface ITestEnvironment
+ */
+export interface ITestEnvironment<ITestPropertiesSchema> extends IBaseTestEnvironment<ITestPropertiesSchema>{
+    /**
+     * A collection of resources used within the test environment that need to be cleaned up once test finishes.
+     * @type {ITestEnvironmentResources}
+     * @memberof ITestEnvironment
+     */
+    resources?: ITestEnvironmentResources;
+}

__tests__/__src__/environment/ITestEnvironmentResources.ts

@@ -0,0 +1,56 @@
+/*
+* This program and the accompanying materials are made available under the terms of the
+* Eclipse Public License v2.0 which accompanies this distribution, and is available at
+* https://www.eclipse.org/legal/epl-v20.html
+*
+* SPDX-License-Identifier: EPL-2.0
+*
+* Copyright Contributors to the Zowe Project.
+*
+*/
+
+import { AbstractSession } from "@zowe/imperative";
+import { ICommonJobParms, IJob } from "../../../packages/zosjobs";
+
+/**
+ * Represents the resources used within the test environment.
+ * @export
+ * @interface ITestEnvironmentResources
+ */
+export interface ITestEnvironmentResources {
+    /**
+     * Array of local file paths used within the test environment.
+     * @type {string[]}
+     */
+    localFiles: string[];
+
+    /**
+     * Array of mainframe uss files used within the test environment.
+     * @type {string[]}
+     */
+    files: string[];
+
+    /**
+     * Array of job objects representing jobs submitted to the mainframe during the test.
+     * @type {IJob[]}
+     */
+    jobs: IJob[];
+
+    /**
+     * Array of job data containing jobname and jobid, used to track jobs within the test environment.
+     * @type {ICommonJobParms[]}
+     */
+    jobData: ICommonJobParms[]; // Contains jobname and jobid
+
+    /**
+     * Array of dataset names used within the test environment.
+     * @type {string[]}
+     */
+    datasets: string[];
+
+    /**
+     * The session used for interacting with z/OS systems during the test, if applicable.
+     * @type {AbstractSession}
+     */
+    session?: AbstractSession;
+}