@salesforce/cli-plugins-testkit 2.5.2 → 3.0.0

package/lib/execCmd.d.ts

@@ -4,30 +4,39 @@ import { SfError } from '@salesforce/core';
 import { Duration } from '@salesforce/kit';
 import { AnyJson, Many } from '@salesforce/ts-types';
 import { ExecOptions, ShellString } from 'shelljs';
-declare type Collection = Record<string, AnyJson> | Array<Record<string, AnyJson>>;
-export interface ExecCmdOptions extends ExecOptions {
+export declare type CLI = 'inherit' | 'sfdx' | 'sf';
+declare type BaseExecOptions = {
     /**
      * Throws if this exit code is not returned by the child process.
      */
     ensureExitCode?: number;
     /**
-     * The base CLI that the plugin is used in. This is used primarily for changing the behavior
-     * of JSON parsing and types.
+     * The executable that should be used for execCmd.
+     * - inherit uses TESTKIT_EXECUTABLE_PATH to determine the executable. If it's not set it defaults to the local bin/dev
+     * - sfdx refers to the globally installed sfdx executable
+     * - sf refers to the globally installed sfdx executable
      */
-    cli?: 'sfdx' | 'sf';
+    cli?: CLI;
+};
+export declare type ExecCmdOptions = ExecOptions & BaseExecOptions;
+declare type ExcludeMethods<T> = Pick<T, NonNullable<{
+    [K in keyof T]: T[K] extends (_: any) => any ? never : K;
+}[keyof T]>>;
+declare type JsonOutput<T> = {
+    status: number;
+    result: T;
+} & Partial<ExcludeMethods<SfError>>;
+export interface ExecCmdResult<T> {
     /**
-     * Answers to supply to any prompts. This does NOT work on windows.
+     * Command output parsed as JSON, if `--json` param present.
      */
-    answers?: string[];
-}
-export interface ExecCmdResult {
+    jsonOutput?: JsonOutput<T>;
     /**
      * Command output from the shell.
      *
      * @see https://www.npmjs.com/package/shelljs#execcommand--options--callback
      */
     shellOutput: ShellString;
-    jsonOutput?: unknown;
     /**
      * The JsonParseError if parsing failed.
      */
@@ -37,27 +46,6 @@ export interface ExecCmdResult {
      */
     execCmdDuration: Duration;
 }
-declare type ExcludeMethods<T> = Pick<T, NonNullable<{
-    [K in keyof T]: T[K] extends (_: any) => any ? never : K;
-}[keyof T]>>;
-export interface SfdxExecCmdResult<T = Collection> extends ExecCmdResult {
-    /**
-     * Command output parsed as JSON, if `--json` param present.
-     */
-    jsonOutput?: {
-        status: number;
-        result: T;
-    } & Partial<ExcludeMethods<SfError>>;
-}
-export interface SfExecCmdResult<T = Collection> extends ExecCmdResult {
-    /**
-     * Command output parsed as JSON, if `--json` param present.
-     */
-    jsonOutput?: {
-        status: number;
-        result: T;
-    } & Partial<ExcludeMethods<SfError>>;
-}
 /**
  * Synchronously execute a command with the provided options in a child process.
  *
@@ -66,6 +54,7 @@ export interface SfExecCmdResult<T = Collection> extends ExecCmdResult {
  *    2. `timeout` = 3,600,000 (1 hour)
  *    3. `env` = process.env
  *    4. `silent` = true (child process output not written to the console)
+ *    5. `cli` = 'inherit' (use the TESTKIT_EXECUTABLE_PATH env var or `bin/dev` if not set for executing commands)
  *
  * Other defaults:
  *
@@ -76,40 +65,12 @@ export interface SfExecCmdResult<T = Collection> extends ExecCmdResult {
  * @param options The options used to run the command.
  * @returns The child process exit code, stdout, stderr, cmd run time, and the parsed JSON if `--json` param present.
  */
-export declare function execCmd<T = Collection>(cmd: string, options?: ExecCmdOptions & {
+export declare function execCmd<T = AnyJson>(cmd: string, options?: ExecCmdOptions & {
     async?: false;
-    cli?: 'sfdx';
-}): SfdxExecCmdResult<T>;
-export declare function execCmd<T = Collection>(cmd: string, options?: ExecCmdOptions & {
-    async?: false;
-    cli?: 'sf';
-}): SfExecCmdResult<T>;
-/**
- * Asynchronously execute a command with the provided options in a child process.
- *
- * Option defaults:
- *    1. `cwd` = process.cwd()
- *    2. `timeout` = 3,600,000 (1 hour)
- *    3. `env` = process.env
- *    4. `silent` = true (child process output not written to the console)
- *
- * Other defaults:
- *
- *    @see www.npmjs.com/package/shelljs#execcommand--options--callback
- *    @see www.nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback
- *
- * @param cmd The command string to be executed by a child process.
- * @param options The options used to run the command.
- * @returns The child process exit code, stdout, stderr, cmd run time, and the parsed JSON if `--json` param present.
- */
-export declare function execCmd<T = Collection>(cmd: string, options: ExecCmdOptions & {
+}): ExecCmdResult<T>;
+export declare function execCmd<T = AnyJson>(cmd: string, options: ExecCmdOptions & {
     async: true;
-    cli?: 'sfdx';
-}): Promise<SfdxExecCmdResult<T>>;
-export declare function execCmd<T = Collection>(cmd: string, options: ExecCmdOptions & {
-    async: true;
-    cli?: 'sf';
-}): Promise<SfExecCmdResult<T>>;
+}): Promise<ExecCmdResult<T>>;
 export declare enum Interaction {
     DOWN = "\u001B[B",
     UP = "\u001B[A",
@@ -125,9 +86,7 @@ export declare type InteractiveCommandExecutionResult = {
     stderr: string;
     duration: Duration;
 };
-export declare type InteractiveCommandExecutionOptions = {
-    ensureExitCode?: number;
-} & SpawnOptionsWithoutStdio;
+export declare type InteractiveCommandExecutionOptions = BaseExecOptions & SpawnOptionsWithoutStdio;
 /**
  * A map of questions and answers to be used in an interactive command.
  *

package/lib/execCmd.js

@@ -17,15 +17,13 @@ const debug_1 = require("debug");
 const shelljs = require("shelljs");
 const shelljs_1 = require("shelljs");
 const stripAnsi = require("strip-ansi");
-const DEFAULT_EXEC_OPTIONS = {
-    cli: 'sfdx',
-};
 const buildCmdOptions = (options) => {
     const defaults = {
-        env: Object.assign({}, process.env),
+        env: { ...process.env, ...options?.env },
         cwd: process.cwd(),
         timeout: kit_1.Duration.hours(1).milliseconds,
         silent: true,
+        cli: 'inherit',
     };
     const shellOverride = kit_1.env.getString('TESTKIT_EXEC_SHELL');
     if (shellOverride) {
@@ -56,19 +54,20 @@ const getExitCodeError = (cmd, expectedCode, output) => {
     return Error(`Unexpected exit code for command: ${cmd}. Expected: ${expectedCode} Actual: ${output.code} ${errorDetails}`);
 };
 /**
- * Build a command string using an optional executable path for use by `execCmd`.
+ * Determine the executable path for use by `execCmd`.
  *
- * The executable preference order is:
- *    2. TESTKIT_EXECUTABLE_PATH env var
- *    3. `bin/dev` (default)
+ * If the cli is 'inherit', the executable preference order is:
+ *    1. TESTKIT_EXECUTABLE_PATH env var
+ *    2. `bin/dev` (default)
  *
- * @param cmdArgs The command name, args, and param as a string. E.g., `"force:user:create -a testuser1"`
  * @returns The command string with CLI executable. E.g., `"node_modules/bin/sfdx force:user:create -a testuser1"`
  */
-const buildCmd = (cmdArgs, options) => {
-    const debug = (0, debug_1.default)('testkit:buildCmd');
-    const bin = kit_1.env.getString('TESTKIT_EXECUTABLE_PATH') ??
-        (0, path_1.join)(process.cwd(), 'bin', process.platform === 'win32' ? 'dev.cmd' : 'dev');
+const determineExecutable = (cli = 'inherit') => {
+    const debug = (0, debug_1.default)('testkit:determineExecutable');
+    const bin = cli === 'inherit'
+        ? kit_1.env.getString('TESTKIT_EXECUTABLE_PATH') ??
+            (0, path_1.join)(process.cwd(), 'bin', process.platform === 'win32' ? 'dev.cmd' : 'dev')
+        : cli;
     const which = shelljs.which(bin);
     let resolvedPath = (0, path_1.resolve)(bin);
     // If which finds the path in the system path, use that.
@@ -78,14 +77,13 @@ const buildCmd = (cmdArgs, options) => {
     else if (!fs.existsSync(bin)) {
         throw new Error(`Cannot find specified executable path: ${bin}`);
     }
-    debug(`Using executable path: ${bin}`);
     debug(`Resolved executable path: ${resolvedPath}`);
-    if (options?.answers && process.platform !== 'win32') {
-        return `printf "${options.answers.join('\\n')}" | ${bin} ${cmdArgs}`;
-    }
-    else {
-        return `${bin} ${cmdArgs}`;
-    }
+    debug(`Using executable path: ${bin}`);
+    return bin;
+};
+const buildCmd = (cmdArgs, options) => {
+    const bin = determineExecutable(options?.cli);
+    return `${bin} ${cmdArgs}`;
 };
 const execCmdSync = (cmd, options) => {
     const debug = (0, debug_1.default)('testkit:execCmd');
@@ -142,22 +140,12 @@ const execCmdAsync = async (cmd, options) => {
     });
     return resultPromise;
 };
-function execCmd(cmd, options = DEFAULT_EXEC_OPTIONS) {
-    if (options.cli === 'sf') {
-        if (options.async) {
-            return execCmdAsync(cmd, options);
-        }
-        else {
-            return execCmdSync(cmd, options);
-        }
+function execCmd(cmd, options) {
+    if (options?.async) {
+        return execCmdAsync(cmd, options);
     }
     else {
-        if (options.async) {
-            return execCmdAsync(cmd, options);
-        }
-        else {
-            return execCmdSync(cmd, options);
-        }
+        return execCmdSync(cmd, options);
     }
 }
 exports.execCmd = execCmd;
@@ -210,7 +198,7 @@ var Interaction;
 async function execInteractiveCmd(command, answers, options = {}) {
     const debug = (0, debug_1.default)('testkit:execInteractiveCmd');
     return new Promise((resolve, reject) => {
-        const bin = buildCmd('').trim();
+        const bin = determineExecutable(options?.cli).trim();
         const startTime = process.hrtime();
         const opts = process.platform === 'win32'
             ? { shell: true, cwd: process.cwd(), ...options }

package/lib/genUniqueString.d.ts

@@ -6,4 +6,4 @@
  * @param {string} template - can contain a replaceable string (%s)
  * @returns {string}
  */
-export declare const genUniqueString: (template?: string | undefined) => string;
+export declare const genUniqueString: (template?: string) => string;

package/lib/hubAuth.d.ts

@@ -1,9 +1,4 @@
-export declare enum AuthStrategy {
-    JWT = "JWT",
-    AUTH_URL = "AUTH_URL",
-    REUSE = "REUSE",
-    NONE = "NONE"
-}
+export declare type DevhubAuthStrategy = 'AUTO' | 'JWT' | 'AUTH_URL' | 'REUSE' | 'NONE';
 export declare const prepareForJwt: (homeDir: string) => string;
 export declare const prepareForAuthUrl: (homeDir: string) => string;
 /**
@@ -18,7 +13,8 @@ export declare const prepareForAuthUrl: (homeDir: string) => string;
  *     optional but recommended: TESTKIT_HUB_INSTANCE
  *   required for AuthUrl: TESTKIT_AUTH_URL
  */
-export declare const testkitHubAuth: (homeDir: string, authStrategy?: AuthStrategy) => void;
+export declare const testkitHubAuth: (homeDir: string, authStrategy?: DevhubAuthStrategy) => void;
+export declare const getAuthStrategy: () => DevhubAuthStrategy;
 /**
  * For scenarios where a hub has already been authenticated in the environment and the username is provided,
  * set the environment variables from the existing hub's information.
@@ -31,4 +27,4 @@ export declare const testkitHubAuth: (homeDir: string, authStrategy?: AuthStrate
  *  TESTKIT_JWT_KEY,TESTKIT_JWT_CLIENT_ID,TESTKIT_HUB_INSTANCE (if using jwt)
  *
  */
-export declare const transferExistingAuthToEnv: (authStrategy?: AuthStrategy) => void;
+export declare const transferExistingAuthToEnv: (authStrategy: DevhubAuthStrategy) => void;

package/lib/hubAuth.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.transferExistingAuthToEnv = exports.testkitHubAuth = exports.prepareForAuthUrl = exports.prepareForJwt = exports.AuthStrategy = void 0;
+exports.transferExistingAuthToEnv = exports.getAuthStrategy = exports.testkitHubAuth = exports.prepareForAuthUrl = exports.prepareForJwt = void 0;
 /*
  * Copyright (c) 2020, salesforce.com, inc.
  * All rights reserved.
@@ -13,15 +13,6 @@ const fs = require("fs");
 const shell = require("shelljs");
 const debug_1 = require("debug");
 const kit_1 = require("@salesforce/kit");
-// this seems to be a known eslint error for enums
-// eslint-disable-next-line no-shadow
-var AuthStrategy;
-(function (AuthStrategy) {
-    AuthStrategy["JWT"] = "JWT";
-    AuthStrategy["AUTH_URL"] = "AUTH_URL";
-    AuthStrategy["REUSE"] = "REUSE";
-    AuthStrategy["NONE"] = "NONE";
-})(AuthStrategy = exports.AuthStrategy || (exports.AuthStrategy = {}));
 const DEFAULT_INSTANCE_URL = 'https://login.salesforce.com';
 /**
  * Function examines the env var TESTKIT_JWT_KEY to determine if it needs to be
@@ -75,14 +66,14 @@ exports.prepareForAuthUrl = prepareForAuthUrl;
  *     optional but recommended: TESTKIT_HUB_INSTANCE
  *   required for AuthUrl: TESTKIT_AUTH_URL
  */
-const testkitHubAuth = (homeDir, authStrategy = getAuthStrategy()) => {
+const testkitHubAuth = (homeDir, authStrategy = (0, exports.getAuthStrategy)()) => {
     const logger = (0, debug_1.debug)('testkit:authFromStubbedHome');
     const execOpts = { silent: true };
     const shellOverride = kit_1.env.getString('TESTKIT_EXEC_SHELL');
     if (shellOverride) {
         execOpts.shell = shellOverride;
     }
-    if (authStrategy === AuthStrategy.JWT) {
+    if (authStrategy === 'JWT') {
         logger('trying jwt auth');
         const jwtKey = (0, exports.prepareForJwt)(homeDir);
         const results = shell.exec(`sfdx auth:jwt:grant -d -u ${kit_1.env.getString('TESTKIT_HUB_USERNAME', '')} -i ${kit_1.env.getString('TESTKIT_JWT_CLIENT_ID', '')} -f ${jwtKey} -r ${kit_1.env.getString('TESTKIT_HUB_INSTANCE', DEFAULT_INSTANCE_URL)}`, execOpts);
@@ -91,7 +82,7 @@ const testkitHubAuth = (homeDir, authStrategy = getAuthStrategy()) => {
         }
         return;
     }
-    if (authStrategy === AuthStrategy.AUTH_URL) {
+    if (authStrategy === 'AUTH_URL') {
         logger('trying to authenticate with AuthUrl');
         const tmpUrl = (0, exports.prepareForAuthUrl)(homeDir);
         const shellOutput = shell.exec(`sfdx auth:sfdxurl:store -d -f ${tmpUrl}`, execOpts);
@@ -108,18 +99,19 @@ const getAuthStrategy = () => {
     if (kit_1.env.getString('TESTKIT_JWT_CLIENT_ID') &&
         kit_1.env.getString('TESTKIT_HUB_USERNAME') &&
         kit_1.env.getString('TESTKIT_JWT_KEY')) {
-        return AuthStrategy.JWT;
+        return 'JWT';
     }
     // you provided a username but not an auth url, so you must already have an auth that you want to re-use
     if (kit_1.env.getString('TESTKIT_HUB_USERNAME') && !kit_1.env.getString('TESTKIT_AUTH_URL')) {
-        return AuthStrategy.REUSE;
+        return 'REUSE';
     }
     // auth url alone
     if (kit_1.env.getString('TESTKIT_AUTH_URL')) {
-        return AuthStrategy.AUTH_URL;
+        return 'AUTH_URL';
     }
-    return AuthStrategy.NONE;
+    return 'NONE';
 };
+exports.getAuthStrategy = getAuthStrategy;
 /**
  * For scenarios where a hub has already been authenticated in the environment and the username is provided,
  * set the environment variables from the existing hub's information.
@@ -132,11 +124,10 @@ const getAuthStrategy = () => {
  *  TESTKIT_JWT_KEY,TESTKIT_JWT_CLIENT_ID,TESTKIT_HUB_INSTANCE (if using jwt)
  *
  */
-const transferExistingAuthToEnv = (authStrategy = getAuthStrategy()) => {
-    // nothing to do if the variables are already provided
-    if (authStrategy !== AuthStrategy.REUSE)
+const transferExistingAuthToEnv = (authStrategy) => {
+    if (authStrategy !== 'REUSE')
         return;
-    const logger = (0, debug_1.debug)('testkit:AuthReuse');
+    const logger = (0, debug_1.debug)('testkit:transferExistingAuthToEnv');
     const devhub = kit_1.env.getString('TESTKIT_HUB_USERNAME', '');
     logger(`reading ${devhub}.json`);
     const authFileName = `${devhub}.json`;

package/lib/index.js

@@ -7,7 +7,11 @@
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];

package/lib/testSession.d.ts

@@ -1,9 +1,19 @@
 import { RetryConfig } from 'ts-retry-promise';
 import { AsyncOptionalCreatable } from '@salesforce/kit';
-import { AnyJson, Optional } from '@salesforce/ts-types';
-import * as shell from 'shelljs';
+import { Optional } from '@salesforce/ts-types';
+import { AuthFields } from '@salesforce/core';
 import { TestProject, TestProjectOptions } from './testProject';
-import { AuthStrategy } from './hubAuth';
+import { DevhubAuthStrategy } from './hubAuth';
+export declare type ScratchOrgConfig = {
+    executable?: 'sfdx' | 'sf';
+    config?: string;
+    duration?: number;
+    alias?: string;
+    setDefault?: boolean;
+    edition?: 'developer' | 'enterprise' | 'group' | 'professional' | 'partner-developer' | 'partner-enterprise' | 'partner-group' | 'partner-professional';
+    username?: string;
+    wait?: number;
+};
 export interface TestSessionOptions {
     /**
      * Specify a different location for the test session.
@@ -14,17 +24,17 @@ export interface TestSessionOptions {
      */
     project?: TestProjectOptions;
     /**
-     * Commands to run as setup for tests.  All must have exitCode == 0 or session
-     * creation will throw.  Any org:create commands run as setup commands will
-     * be deleted as part of `TestSession.clean()`.
+     * Scratch orgs to create as part of setup.  All must be created successfully or session
+     * create will throw.  Scratch orgs created as part of setup will be deleted as part of
+     * `TestSession.clean()`.
      */
-    setupCommands?: string[];
+    scratchOrgs?: ScratchOrgConfig[];
     /**
      * The preferred auth method to use
      */
-    authStrategy?: keyof typeof AuthStrategy;
+    devhubAuthStrategy?: DevhubAuthStrategy;
     /**
-     * The number of times to retry the setupCommands after the initial attempt if it fails. Will be overridden by TESTKIT_SETUP_RETRIES environment variable.
+     * The number of times to retry the scratch org create after the initial attempt if it fails. Will be overridden by TESTKIT_SETUP_RETRIES environment variable.
      */
     retries?: number;
 }
@@ -44,8 +54,8 @@ export interface TestSessionOptions {
  *   TESTKIT_PROJECT_DIR = a SFDX project to use for testing. the tests will use this project directly.
  *   TESTKIT_SAVE_ARTIFACTS = prevents a test session from deleting orgs, projects, and test sessions.
  *   TESTKIT_ENABLE_ZIP = allows zipping the session dir when this is true
- *   TESTKIT_SETUP_RETRIES = number of times to retry the setupCommands after the initial attempt before throwing an error
- *   TESTKIT_SETUP_RETRIES_TIMEOUT = milliseconds to wait before the next retry of setupCommands. Defaults to 5000
+ *   TESTKIT_SETUP_RETRIES = number of times to retry the org creates after the initial attempt before throwing an error
+ *   TESTKIT_SETUP_RETRIES_TIMEOUT = milliseconds to wait before the next retry of scratch org creations. Defaults to 5000
  *   TESTKIT_EXEC_SHELL = the shell to use for all testkit shell executions rather than the shelljs default.
  *
  *   TESTKIT_HUB_USERNAME = username of an existing hub (authenticated before creating a session)
@@ -60,14 +70,13 @@ export declare class TestSession extends AsyncOptionalCreatable<TestSessionOptio
     dir: string;
     homeDir: string;
     project?: TestProject;
-    setup?: AnyJson[] | shell.ShellString;
     rmRetryConfig: Partial<RetryConfig<void>>;
+    orgs: Map<string, AuthFields>;
     private debug;
     private cwdStub?;
     private overriddenDir?;
     private sandbox;
-    private orgs;
-    private setupRetries;
+    private retries;
     private zipDir;
     private options;
     private shelljsExecOptions;
@@ -108,6 +117,6 @@ export declare class TestSession extends AsyncOptionalCreatable<TestSessionOptio
     protected init(): Promise<void>;
     private deleteOrgs;
     private rmSessionDir;
-    private setupCommands;
+    private createOrgs;
     private sleep;
 }

package/lib/testSession.js

@@ -11,7 +11,6 @@ const fs = require("fs");
 const path = require("path");
 const debug_1 = require("debug");
 const kit_1 = require("@salesforce/kit");
-const ts_types_1 = require("@salesforce/ts-types");
 const sinon_1 = require("sinon");
 const shell = require("shelljs");
 const stripAnsi = require("strip-ansi");
@@ -35,8 +34,8 @@ const hubAuth_1 = require("./hubAuth");
  *   TESTKIT_PROJECT_DIR = a SFDX project to use for testing. the tests will use this project directly.
  *   TESTKIT_SAVE_ARTIFACTS = prevents a test session from deleting orgs, projects, and test sessions.
  *   TESTKIT_ENABLE_ZIP = allows zipping the session dir when this is true
- *   TESTKIT_SETUP_RETRIES = number of times to retry the setupCommands after the initial attempt before throwing an error
- *   TESTKIT_SETUP_RETRIES_TIMEOUT = milliseconds to wait before the next retry of setupCommands. Defaults to 5000
+ *   TESTKIT_SETUP_RETRIES = number of times to retry the org creates after the initial attempt before throwing an error
+ *   TESTKIT_SETUP_RETRIES_TIMEOUT = milliseconds to wait before the next retry of scratch org creations. Defaults to 5000
  *   TESTKIT_EXEC_SHELL = the shell to use for all testkit shell executions rather than the shelljs default.
  *
  *   TESTKIT_HUB_USERNAME = username of an existing hub (authenticated before creating a session)
@@ -50,8 +49,8 @@ class TestSession extends kit_1.AsyncOptionalCreatable {
         super(options);
         // this is stored on the class so that tests can set it to something much lower than default
         this.rmRetryConfig = { retries: 12, delay: 5000 };
+        this.orgs = new Map();
         this.sandbox = (0, sinon_1.createSandbox)();
-        this.orgs = [];
         this.shelljsExecOptions = {
             silent: true,
         };
@@ -60,7 +59,7 @@ class TestSession extends kit_1.AsyncOptionalCreatable {
         this.zipDir = zip_1.zipDir;
         this.createdDate = new Date();
         this.id = (0, genUniqueString_1.genUniqueString)(`${this.createdDate.valueOf()}%s`);
-        this.setupRetries = kit_1.env.getNumber('TESTKIT_SETUP_RETRIES', this.options.retries) || 0;
+        this.retries = kit_1.env.getNumber('TESTKIT_SETUP_RETRIES', this.options.retries) || 0;
         const shellOverride = kit_1.env.getString('TESTKIT_EXEC_SHELL');
         if (shellOverride) {
             this.shelljsExecOptions.shell = shellOverride;
@@ -88,8 +87,9 @@ class TestSession extends kit_1.AsyncOptionalCreatable {
         }
         // Write the test session options used to create this session
         fs.writeFileSync(path.join(this.dir, 'testSessionOptions.json'), JSON.stringify(JSON.parse(JSON.stringify(this.options))));
-        const authStrategy = this.options.authStrategy ? hubAuth_1.AuthStrategy[this.options.authStrategy] : undefined;
-        // have to grab this before we change the home
+        const authStrategy = !this.options.devhubAuthStrategy || this.options.devhubAuthStrategy === 'AUTO'
+            ? (0, hubAuth_1.getAuthStrategy)()
+            : this.options.devhubAuthStrategy;
         (0, hubAuth_1.transferExistingAuthToEnv)(authStrategy);
         // Set the homedir used by this test, on the TestSession and the process
         process.env.USERPROFILE = process.env.HOME = this.homeDir = kit_1.env.getString('TESTKIT_HOMEDIR', this.dir);
@@ -153,13 +153,13 @@ class TestSession extends kit_1.AsyncOptionalCreatable {
     }
     async init() {
         // Run all setup commands
-        await this.setupCommands(this.options.setupCommands);
+        await this.createOrgs(this.options.scratchOrgs);
         this.debug('Created testkit session:');
         this.debug(`  ID: ${this.id}`);
         this.debug(`  Created Date: ${this.createdDate}`);
         this.debug(`  Dir: ${this.dir}`);
         this.debug(`  Home Dir: ${this.homeDir}`);
-        if (this.orgs?.length) {
+        if (this.orgs.size > 0) {
             this.debug('  Orgs: ', this.orgs);
         }
         if (this.project) {
@@ -167,12 +167,13 @@ class TestSession extends kit_1.AsyncOptionalCreatable {
         }
     }
     async deleteOrgs() {
-        if (!kit_1.env.getString('TESTKIT_ORG_USERNAME') && this.orgs?.length) {
-            const orgs = this.orgs.slice();
-            for (const org of orgs) {
+        if (!kit_1.env.getString('TESTKIT_ORG_USERNAME') && this.orgs.size > 0) {
+            for (const org of [...this.orgs.keys()]) {
+                if (org === 'default')
+                    continue;
                 this.debug(`Deleting test org: ${org}`);
-                const rv = shell.exec(`sfdx force:org:delete -u ${org} -p`, this.shelljsExecOptions);
-                this.orgs = this.orgs.filter((o) => o !== org);
+                const rv = shell.exec(`sf env delete scratch -o ${org} -p`, this.shelljsExecOptions);
+                this.orgs.delete(org);
                 if (rv.code !== 0) {
                     // Must still delete the session dir if org:delete fails
                     await this.rmSessionDir();
@@ -192,77 +193,74 @@ class TestSession extends kit_1.AsyncOptionalCreatable {
     }
     // Executes commands and keeps track of any orgs created.
     // Throws if any commands return a non-zero exitCode.
-    async setupCommands(cmds) {
-        const dbug = (0, debug_1.debug)('testkit:setupCommands');
+    async createOrgs(orgs = []) {
+        const dbug = (0, debug_1.debug)('testkit:createOrgs');
         const setup = () => {
-            if (cmds) {
-                this.setup = [];
-                for (let cmd of cmds) {
-                    if (cmd.includes('org:create')) {
-                        // Don't create orgs if we are supposed to reuse one from the env
-                        const org = kit_1.env.getString('TESTKIT_ORG_USERNAME');
-                        if (org) {
-                            dbug(`Not creating a new org. Reusing TESTKIT_ORG_USERNAME of: ${org}`);
-                            this.setup.push({ result: { username: org } });
-                            continue;
-                        }
-                    }
-                    // Detect when running sfdx cli commands
-                    if (cmd.split(' ')[0].includes('sfdx')) {
-                        if (!shell.which('sfdx')) {
-                            throw new Error('sfdx executable not found for running sfdx setup commands');
-                        }
-                        // Add the json flag if it looks like an sfdx command so we can return
-                        // parsed json in the command return.
-                        if (!cmd.includes('--json')) {
-                            cmd += ' --json';
-                        }
-                    }
-                    const rv = shell.exec(cmd, this.shelljsExecOptions);
-                    rv.stdout = stripAnsi(rv.stdout);
-                    rv.stderr = stripAnsi(rv.stderr);
-                    if (rv.code !== 0) {
-                        const io = cmd.includes('--json') ? rv.stdout : rv.stderr;
-                        throw Error(`Setup command ${cmd} failed due to: ${io}`);
-                    }
-                    dbug(`Output for setup cmd ${cmd} is:\n${rv.stdout}`);
-                    // Automatically parse json results
-                    if (cmd.includes('--json')) {
-                        try {
-                            const jsonOutput = (0, kit_1.parseJson)(rv.stdout);
-                            // keep track of all org creates
-                            if (cmd.includes('org:create')) {
-                                const username = (0, ts_types_1.getString)(jsonOutput, 'result.username');
-                                if (username) {
-                                    dbug(`Saving org username: ${username} from ${cmd}`);
-                                    this.orgs.push(username);
-                                }
-                            }
-                            this.setup.push(jsonOutput);
-                        }
-                        catch (err) {
-                            dbug(`Failed command output JSON parsing due to:\n${err.message}`);
-                            this.setup.push(rv);
-                        }
-                    }
-                    else {
-                        this.setup.push(rv);
-                    }
+            for (const org of orgs) {
+                // Don't create orgs if we are supposed to reuse one from the env
+                const orgUsername = kit_1.env.getString('TESTKIT_ORG_USERNAME');
+                if (orgUsername) {
+                    dbug(`Not creating a new org. Reusing TESTKIT_ORG_USERNAME of: ${org}`);
+                    this.orgs.set(orgUsername, { username: orgUsername });
+                    continue;
+                }
+                const executable = org.executable ?? 'sf';
+                if (!shell.which(executable)) {
+                    throw new Error(`${executable} executable not found for creating scratch orgs`);
+                }
+                let baseCmd = executable === 'sf' ? `${executable} env create scratch --json` : `${executable} force:org:create --json`;
+                if (org.config) {
+                    baseCmd += ` -f ${org.config}`;
+                }
+                if (org.alias) {
+                    baseCmd += ` -a ${org.alias}`;
+                }
+                if (org.duration) {
+                    baseCmd += executable === 'sf' ? ` -y ${org.duration}` : ` -d ${org.duration}`;
+                }
+                if (org.setDefault) {
+                    baseCmd += executable === 'sf' ? ' -d' : ' -s';
+                }
+                if (org.username) {
+                    if (org.executable === 'sfdx')
+                        baseCmd += ` username=${org.username}`;
+                    else
+                        throw new Error('username property is not supported by sf env create scratch');
+                }
+                if (org.edition) {
+                    baseCmd += executable === 'sf' ? ` -e ${org.edition}` : ` edition=${org.edition}`;
+                }
+                if (org.wait) {
+                    baseCmd += `-w ${org.wait}`;
+                }
+                const rv = shell.exec(baseCmd, this.shelljsExecOptions);
+                rv.stdout = stripAnsi(rv.stdout);
+                rv.stderr = stripAnsi(rv.stderr);
+                if (rv.code !== 0) {
+                    throw Error(`${baseCmd} failed due to: ${rv.stdout}`);
+                }
+                dbug(`Output for ${baseCmd} is:\n${rv.stdout}`);
+                const jsonOutput = (0, kit_1.parseJson)(rv.stdout);
+                const username = jsonOutput.result.username;
+                dbug(`Saving org username: ${username} from ${baseCmd}`);
+                this.orgs.set(username, jsonOutput.result.authFields);
+                if (org.setDefault) {
+                    this.orgs.set('default', jsonOutput.result.authFields);
                 }
             }
         };
         let attempts = 0;
         let completed = false;
         const timeout = new kit_1.Duration(kit_1.env.getNumber('TESTKIT_SETUP_RETRIES_TIMEOUT') ?? 5000, kit_1.Duration.Unit.MILLISECONDS);
-        while (!completed && attempts <= this.setupRetries) {
+        while (!completed && attempts <= this.retries) {
             try {
-                dbug(`Executing setup commands (attempt ${attempts + 1} of ${this.setupRetries + 1})`);
+                dbug(`Executing org create(s) (attempt ${attempts + 1} of ${this.retries + 1})`);
                 setup();
                 completed = true;
             }
             catch (err) {
                 attempts += 1;
-                if (attempts > this.setupRetries) {
+                if (attempts > this.retries) {
                     throw err;
                 }
                 dbug(`Setup failed. waiting ${timeout.seconds} seconds before next attempt...`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/cli-plugins-testkit",
   "description": "Provides test utilities to assist Salesforce CLI plug-in authors with writing non-unit tests (NUT).",
-  "version": "2.5.2",
+  "version": "3.0.0",
   "author": "Salesforce",
   "license": "BSD-3-Clause",
   "main": "lib/index.js",
@@ -42,7 +42,7 @@
     "!lib/**/*.map"
   ],
   "dependencies": {
-    "@salesforce/core": "^3.30.8",
+    "@salesforce/core": "^3.30.9",
     "@salesforce/kit": "^1.6.1",
     "@salesforce/ts-types": "^1.5.21",
     "@types/shelljs": "^0.8.11",
@@ -79,7 +79,7 @@
     "pretty-quick": "^3.1.0",
     "sinon": "10.0.0",
     "ts-node": "^10.0.0",
-    "typescript": "^4.1.3"
+    "typescript": "^4.8.4"
   },
   "config": {
     "commitizen": {