feat(testlab): create unique sandbox for each instance to enable parallel testing

BREAKING CHANGE: The TestSandbox constructor changes its signature and behavior
now. It used to take a `path` as the top-level directory of the sandbox. The
new style is illustrated below.

```ts
// Create a sandbox as a unique temporary subdirectory under the rootPath
const sandbox = new TestSandbox(rootPath);

// Create a sandbox in the root path directly
// This is same as the old behavior
const sandbox = new TestSandbox(rootPath, '');
const sandbox = new TestSandbox(rootPath, '.');

// Create a sandbox in the `test1` subdirectory of the root path
const sandbox = new TestSandbox(rootPath, 'test1');
```

Author: raymondfeng

packages/boot/src/__tests__/acceptance/application-metadata.booter.acceptance.ts

@@ -10,7 +10,7 @@ import {BooterApp} from '../fixtures/application';
 
 describe('application metadata booter acceptance tests', () => {
   let app: BooterApp;
-  const sandbox = new TestSandbox(resolve(__dirname, '../../.sandbox'));
+  const sandbox = new TestSandbox(resolve(__dirname, '../../.sandbox'), '.');
 
   beforeEach('reset sandbox', () => sandbox.reset());
   beforeEach(getApp);

packages/testlab/src/__tests__/integration/test-sandbox.integration.ts

@@ -111,7 +111,7 @@ describe('TestSandbox integration tests', () => {
     beforeEach(callSandboxDelete);
 
     it('throws an error when trying to call getPath()', () => {
-      expect(() => sandbox.getPath()).to.throw(ERR);
+      expect(() => sandbox.path).to.throw(ERR);
     });
 
     it('throws an error when trying to call mkdir()', async () => {
@@ -146,11 +146,11 @@ describe('TestSandbox integration tests', () => {
   }
 
   function givenPath() {
-    path = sandbox.getPath();
+    path = sandbox.path;
   }
 
   async function deleteSandbox() {
     if (!(await pathExists(path))) return;
-    await remove(sandbox.getPath());
+    await remove(sandbox.path);
   }
 });

packages/testlab/src/__tests__/unit/test-sandbox.unit.ts

@@ -0,0 +1,40 @@
+// Copyright IBM Corp. 2020. All Rights Reserved.
+// Node module: @loopback/testlab
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {dirname, join, resolve} from 'path';
+import {expect, TestSandbox} from '../..';
+
+const SANDBOX_PATH = resolve(__dirname, '../../.sandbox');
+
+describe('TestSandbox', () => {
+  it('creates a subdir by default', () => {
+    const sandbox = new TestSandbox(SANDBOX_PATH);
+    expect(sandbox.path).to.not.eql(SANDBOX_PATH);
+    expect(dirname(sandbox.path)).to.eql(SANDBOX_PATH);
+  });
+
+  it('creates unique subdir by default', () => {
+    const sandbox1 = new TestSandbox(SANDBOX_PATH);
+    const sandbox2 = new TestSandbox(SANDBOX_PATH);
+    expect(sandbox1.path).to.not.eql(sandbox2.path);
+  });
+
+  it('creates a named subdir', () => {
+    const sandbox = new TestSandbox(SANDBOX_PATH, 'd1');
+    expect(sandbox.path).to.not.eql(SANDBOX_PATH);
+    expect(dirname(sandbox.path)).to.eql(SANDBOX_PATH);
+    expect(sandbox.path).to.eql(join(SANDBOX_PATH, 'd1'));
+  });
+
+  it('does not creates a subdir if it is empty string', () => {
+    const sandbox = new TestSandbox(SANDBOX_PATH, '');
+    expect(sandbox.path).to.eql(SANDBOX_PATH);
+  });
+
+  it("does not creates a subdir if it is '.'", () => {
+    const sandbox = new TestSandbox(SANDBOX_PATH, '.');
+    expect(sandbox.path).to.eql(SANDBOX_PATH);
+  });
+});

packages/testlab/src/test-sandbox.ts

@@ -9,12 +9,13 @@ import {
   emptyDir,
   ensureDir,
   ensureDirSync,
+  mkdtempSync,
   pathExists,
   remove,
   writeFile,
   writeJson,
 } from 'fs-extra';
-import {parse, resolve} from 'path';
+import {join, parse, resolve} from 'path';
 
 /**
  * TestSandbox class provides a convenient way to get a reference to a
@@ -37,19 +38,36 @@ export class TestSandbox {
    * Will create a directory if it doesn't already exist. If it exists, you
    * still get an instance of the TestSandbox.
    *
-   * @param path - Path of the TestSandbox. If relative (it will be resolved relative to cwd()).
-   */
-  constructor(path: string) {
-    // resolve ensures path is absolute / makes it absolute (relative to cwd())
-    this._path = resolve(path);
-    ensureDirSync(this.path);
-  }
-
-  /**
-   * Returns the path of the TestSandbox
+   * @example
+   * ```ts
+   * // Create a sandbox as a unique temporary subdirectory under the rootPath
+   * const sandbox = new TestSandbox(rootPath);
+   *
+   * // Create a sandbox in the root path directly
+   * // This is same as the old behavior
+   * const sandbox = new TestSandbox(rootPath, '');
+   * const sandbox = new TestSandbox(rootPath, '.');
+   *
+   * // Create a sandbox in the `test1` subdirectory of the root path
+   * const sandbox = new TestSandbox(rootPath, 'test1');
+   * ```
+   *
+   * @param rootPath - Root path of the TestSandbox. If relative it will be
+   * resolved against the current directory.
+   * @param subdir - Subdirectory for the sandbox. If not provided, the sandbox
+   * will automatically creates a unique temporary subdirectory. This allows
+   * sandboxes with the same root path can be used in parallel during testing.
    */
-  getPath(): string {
-    return this.path;
+  constructor(rootPath: string, subdir?: string) {
+    rootPath = resolve(rootPath);
+    ensureDirSync(rootPath);
+    if (subdir != null) {
+      this._path = resolve(rootPath, subdir);
+    } else {
+      // Create a unique temporary directory under the root path
+      // See https://nodejs.org/api/fs.html#fs_fs_mkdtempsync_prefix_options
+      this._path = mkdtempSync(join(rootPath, `/${process.pid}`));
+    }
   }
 
   /**