feat(testlab): create a test sandbox utility (#877)

* feat(testlab): create a test sandbox utility

* style: add async suffix to promisified versions of functions

* fix(testlab): apply feedback

* fix(testlab): add node 6 polyfill for fs.copyFile

* docs(testlab): add comment on node version for copyFile polyfill

Author: virkt25

packages/cli/test/clone-example.test.js

@@ -3,27 +3,29 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-'use strict';
+('use strict');
 
 const promisify = require('../lib/utils').promisify;
 
 const cloneExampleFromGitHub = require('../generators/example/clone-example');
 const expect = require('@loopback/testlab').expect;
+const TestSandbox = require('@loopback/testlab').TestSandbox;
 const fs = require('fs');
 const glob = promisify(require('glob'));
 const path = require('path');
 const rimraf = promisify(require('rimraf'));
 
 const VALID_EXAMPLE = 'codehub';
-const SANDBOX = path.resolve(__dirname, 'sandbox');
+const SANDBOX_PATH = path.resolve(__dirname, 'sandbox');
+let sandbox;
 
 describe('cloneExampleFromGitHub', function() {
   this.timeout(10000);
-
+  before(createSandbox);
   beforeEach(resetSandbox);
 
   it('extracts all project files', () => {
-    return cloneExampleFromGitHub(VALID_EXAMPLE, SANDBOX)
+    return cloneExampleFromGitHub(VALID_EXAMPLE, SANDBOX_PATH)
       .then(outDir => {
         return Promise.all([
           glob('**', {
@@ -42,7 +44,11 @@ describe('cloneExampleFromGitHub', function() {
       });
   });
 
+  function createSandbox() {
+    sandbox = new TestSandbox(SANDBOX_PATH);
+  }
+
   function resetSandbox() {
-    return rimraf(SANDBOX);
+    sandbox.reset();
   }
 });

packages/testlab/package.json

@@ -21,15 +21,18 @@
   "license": "MIT",
   "dependencies": {
     "@loopback/openapi-spec": "^4.0.0-alpha.20",
+    "@types/rimraf": "^2.0.2",
     "@types/shot": "^3.4.0",
     "@types/sinon": "^2.3.7",
     "@types/supertest": "^2.0.0",
     "@types/swagger-parser": "^4.0.1",
+    "rimraf": "^2.6.2",
     "shot": "^4.0.3",
     "should": "^13.1.3",
     "sinon": "^4.1.2",
     "supertest": "^3.0.0",
-    "swagger-parser": "^4.0.1"
+    "swagger-parser": "^4.0.1",
+    "util.promisify": "^1.0.0"
   },
   "devDependencies": {
     "@loopback/build": "^4.0.0-alpha.9"

packages/testlab/src/test-sandbox.ts

@@ -0,0 +1,122 @@
+// Copyright IBM Corp. 2017,2018. 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 {tmpdir} from 'os';
+import {createHash} from 'crypto';
+import {resolve, join, parse} from 'path';
+import * as util from 'util';
+import {mkdirSync, existsSync, mkdir, copyFile, readFile, writeFile} from 'fs';
+const promisify = util.promisify || require('util.promisify/implementation');
+const rimrafAsync = promisify(require('rimraf'));
+const mkdirAsync = promisify(mkdir);
+
+// tslint:disable-next-line:no-any
+let copyFileAsync: any;
+if (copyFile) {
+  copyFileAsync = promisify(copyFile);
+} else {
+  /**
+   * Taranveer: fs.copyFile wasn't made available till Node 8.5.0. As such this
+   * polyfill is needed for versions of Node prior to that.
+   */
+  copyFileAsync = async function(src: string, target: string) {
+    const readFileAsync = promisify(readFile);
+    const writeFileAsync = promisify(writeFile);
+    const data = await readFileAsync(src);
+    await writeFileAsync(target, data);
+  };
+}
+
+/**
+ * TestSandbox class provides a convenient way to get a reference to a
+ * sandbox folder in which you can perform operations for testing purposes.
+ */
+export class TestSandbox {
+  // Path of the TestSandbox
+  private path: string;
+
+  /**
+   * 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);
+    // Create directory if it doesn't already exist.
+    if (!existsSync(this.path)) {
+      this.create();
+    }
+  }
+
+  /**
+   * Syncronously creates the TestSandbox directory. It is syncronous because
+   * it is called by the constructor.
+   */
+  private create(): void {
+    mkdirSync(this.path);
+  }
+
+  /**
+   * This function ensures a valid instance is being used for operations.
+   */
+  private validateInst() {
+    if (!this.path) {
+      throw new Error(
+        `TestSandbox instance was deleted. Create a new instance.`,
+      );
+    }
+  }
+
+  /**
+   * Returns the path of the TestSandbox
+   */
+  getPath(): string {
+    this.validateInst();
+    return this.path;
+  }
+
+  /**
+   * Resets the TestSandbox. (Remove all files in it).
+   */
+  async reset(): Promise<void> {
+    this.validateInst();
+    await rimrafAsync(this.path);
+    this.create();
+  }
+
+  /**
+   * Deletes the TestSandbox.
+   */
+  async delete(): Promise<void> {
+    this.validateInst();
+    await rimrafAsync(this.path);
+    delete this.path;
+  }
+
+  /**
+   * Makes a directory in the TestSandbox
+   * @param dir Name of directory to create (relative to TestSandbox path)
+   */
+  async mkdir(dir: string): Promise<void> {
+    this.validateInst();
+    await mkdirAsync(resolve(this.path, dir));
+  }
+
+  /**
+   * Copies a file from src to the TestSandbox.
+   * @param src Absolute path of file to be copied to the TestSandbox
+   * @param [dest] Optional. Destination filename of the copy operation
+   * (relative to TestSandbox). Original filename used if not specified.
+   */
+  async copy(src: string, dest?: string): Promise<void> {
+    this.validateInst();
+    dest = dest
+      ? resolve(this.path, dest)
+      : resolve(this.path, parse(src).base);
+    await copyFileAsync(src, dest);
+  }
+}

packages/testlab/src/testlab.ts

@@ -20,3 +20,4 @@ export {sinon, SinonSpy};
 export * from './client';
 export * from './shot';
 export * from './validate-api-spec';
+export * from './test-sandbox';

packages/testlab/test/fixtures/copy-me.txt

@@ -0,0 +1 @@
+Hello World!

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

@@ -0,0 +1,126 @@
+// Copyright IBM Corp. 2017,2018. 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 {TestSandbox, expect} from '../..';
+import {existsSync, readFile as readFile_} from 'fs';
+import {resolve} from 'path';
+import {createHash} from 'crypto';
+import * as util from 'util';
+const promisify = util.promisify || require('util.promisify/implementation');
+const rimraf = require('rimraf');
+const readFile = promisify(readFile_);
+
+describe('TestSandbox integration tests', () => {
+  let sandbox: TestSandbox;
+  let path: string;
+  const COPY_FILE = 'copy-me.txt';
+  const COPY_FILE_PATH = resolve(
+    __dirname,
+    '../../../test/fixtures',
+    COPY_FILE,
+  );
+  let fileContent: string;
+
+  before(getCopyFileContents);
+  beforeEach(createSandbox);
+  beforeEach(givenPath);
+  afterEach(deleteSandbox);
+
+  it('returns path of sandbox and it exists', () => {
+    expect(path).to.be.a.String();
+    expect(existsSync(path)).to.be.True();
+  });
+
+  it('creates a directory in the sandbox', async () => {
+    const dir = 'controllers';
+    await sandbox.mkdir(dir);
+    expect(existsSync(resolve(path, dir))).to.be.True();
+  });
+
+  it('copies a file to the sandbox', async () => {
+    await sandbox.copy(COPY_FILE_PATH);
+    expect(existsSync(resolve(path, COPY_FILE))).to.be.True();
+    await compareFiles(resolve(path, COPY_FILE));
+  });
+
+  it('copies and renames the file to the sandbox', async () => {
+    const rename = 'copy.me.js';
+    await sandbox.copy(COPY_FILE_PATH, rename);
+    expect(existsSync(resolve(path, COPY_FILE))).to.be.False();
+    expect(existsSync(resolve(path, rename))).to.be.True();
+    await compareFiles(resolve(path, rename));
+  });
+
+  it('copies file to a directory', async () => {
+    const dir = 'test';
+    await sandbox.mkdir(dir);
+    const rename = `${dir}/${COPY_FILE}`;
+    await sandbox.copy(COPY_FILE_PATH, rename);
+    expect(existsSync(resolve(path, rename))).to.be.True();
+    await compareFiles(resolve(path, rename));
+  });
+
+  it('deletes the test sandbox', async () => {
+    await sandbox.delete();
+    expect(existsSync(path)).to.be.False();
+  });
+
+  describe('after deleting sandbox', () => {
+    const ERR: string =
+      'TestSandbox instance was deleted. Create a new instance.';
+
+    beforeEach(callSandboxDelete);
+
+    it('throws an error when trying to call getPath()', () => {
+      expect(() => sandbox.getPath()).to.throw(ERR);
+    });
+
+    it('throws an error when trying to call mkdir()', async () => {
+      await expect(sandbox.mkdir('test')).to.be.rejectedWith(ERR);
+    });
+
+    it('throws an error when trying to call copy()', async () => {
+      await expect(sandbox.copy(COPY_FILE_PATH)).to.be.rejectedWith(ERR);
+    });
+
+    it('throws an error when trying to call reset()', async () => {
+      await expect(sandbox.reset()).to.be.rejectedWith(ERR);
+    });
+
+    it('throws an error when trying to call delete() again', async () => {
+      await expect(sandbox.delete()).to.be.rejectedWith(ERR);
+    });
+  });
+
+  async function callSandboxDelete() {
+    await sandbox.delete();
+  }
+
+  async function compareFiles(path1: string) {
+    const file = await readFile(path1, 'utf8');
+    expect(file).to.equal(fileContent);
+  }
+
+  function createSandbox() {
+    sandbox = new TestSandbox(resolve(__dirname, 'sandbox'));
+  }
+
+  function givenPath() {
+    path = sandbox.getPath();
+  }
+
+  function deleteSandbox() {
+    if (!existsSync(path)) return;
+    try {
+      rimraf.sync(sandbox.getPath());
+    } catch (err) {
+      console.log(`Failed to delete sandbox because: ${err}`);
+    }
+  }
+
+  async function getCopyFileContents() {
+    fileContent = await readFile(COPY_FILE_PATH, 'utf8');
+  }
+});

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

@@ -0,0 +1,34 @@
+// Copyright IBM Corp. 2017,2018. 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 {TestSandbox, expect, sinon} from '../..';
+import * as fs from 'fs';
+import {resolve} from 'path';
+
+describe('TestSandbox unit tests', () => {
+  const sandboxPath = resolve(__dirname, 'sandbox');
+  let sandbox: TestSandbox;
+  let mkdirSyncSpy: sinon.SinonSpy;
+
+  beforeEach(createSpies);
+  beforeEach(createSandbox);
+  afterEach(restoreSpies);
+
+  it('created a sandbox using mkdirSync', () => {
+    sinon.assert.calledWith(mkdirSyncSpy, sandboxPath);
+  });
+
+  function createSandbox() {
+    sandbox = new TestSandbox(sandboxPath);
+  }
+
+  function createSpies() {
+    mkdirSyncSpy = sinon.spy(fs, 'mkdirSync');
+  }
+
+  function restoreSpies() {
+    mkdirSyncSpy.restore();
+  }
+});