feat(instructions): add instructions files

commands/RunTests.js

@@ -12,12 +12,14 @@
 const path = require('path')
 const _ = require('lodash')
 const { Command } = require('@adonisjs/ace')
+const debug = require('debug')('adonis:vow:command')
 
 class RunTests extends Command {
-  constructor (runner, cli) {
+  constructor (runner, cli, env) {
     super()
     this.runner = runner
     this.cli = cli
+    this.env = env
   }
 
   /**
@@ -56,7 +58,7 @@ class RunTests extends Command {
    * @return {Array}
    */
   static get inject () {
-    return ['Test/Runner', 'Test/Cli']
+    return ['Test/Runner', 'Test/Cli', 'Adonis/Src/Env']
   }
 
   /**
@@ -74,13 +76,37 @@ class RunTests extends Command {
   _requireVowFile (projectRoot) {
     try {
       require(path.join(projectRoot, 'vowfile'))(this.cli, this.runner)
+      debug('loaded vowfile.js')
     } catch (error) {
       if (error.code !== 'MODULE_NOT_FOUND') {
         throw error
       }
     }
   }
 
+  /**
+   * Loads the `.env.test` file from the application root
+   * directory. If file doesn't exists it will ignore
+   * it.
+   *
+   * @method _requireTestEnvFile
+   * @async
+   *
+   * @param  {String}            projectRoot
+   *
+   * @return {void}
+   *
+   * @private
+   */
+  async _requireTestEnvFile (projectRoot) {
+    const testEnvFile = path.join(projectRoot, '.env.test')
+    const exists = await this.exists(testEnvFile)
+    if (exists) {
+      debug('loading .env.test file to merge the env variables')
+      this.env.load(testEnvFile)
+    }
+  }
+
   /**
    * Handle method called by ace when test command
    * is executed
@@ -98,6 +124,7 @@ class RunTests extends Command {
    */
   async handle ({ type }, { bail, timeout, files, grep, glob }) {
     const projectRoot = this.cli.projectRoot
+    await this._requireTestEnvFile(projectRoot)
     this._requireVowFile(projectRoot)
 
     this.runner.bail(bail || false)
@@ -106,6 +133,7 @@ class RunTests extends Command {
      * If grep statement is defined, use it
      */
     if (grep) {
+      debug('grep term %s', grep)
       this.runner.grep(grep)
     }
 
@@ -129,8 +157,10 @@ class RunTests extends Command {
      * If there is a global timeout set it on
      * runner
      */
-    if (timeout && Number(timeout)) {
-      this.runner.timeout(Number(timeout))
+    timeout = Number(timeout)
+    if (timeout && !isNaN(timeout)) {
+      debug('global timeout %d', timeout)
+      this.runner.timeout(timeout)
     }
 
     /**
@@ -155,6 +185,7 @@ class RunTests extends Command {
           return file.endsWith(selectedFile.trim())
         })
       })
+      debug('post --files filter %j', testFiles)
     }
 
     try {
@@ -164,6 +195,7 @@ class RunTests extends Command {
       if (!process.env.TEST_SERVER_URL) {
         process.env.TEST_SERVER_URL = `http://${process.env.HOST}:${process.env.PORT}`
       }
+      debug('running test server on %s', process.env.TEST_SERVER_URL)
 
       /**
        * Requiring all test files.

instructions.js

@@ -0,0 +1,31 @@
+'use strict'
+
+/*
+ * adonis-vow
+ *
+ * (c) Harminder Virk <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+*/
+
+const path = require('path')
+
+module.exports = async (cli) => {
+  try {
+    const appRoot = cli.helpers.appRoot()
+    /**
+     * Copy vow file
+     */
+    await cli.copy(path.join(__dirname, 'templates/vowfile.js'), path.join(appRoot, 'vowfile.js'))
+    cli.command.completed('create', 'vowfile.js')
+
+    /**
+     * Copy example test case
+     */
+    await cli.copy(path.join(__dirname, 'templates/unitTest.js'), path.join(appRoot, 'test/unit/example.spec.js'))
+    cli.command.completed('create', 'test/unit/example.spec.js')
+  } catch (error) {
+    // ignore the error
+  }
+}

instructions.md

@@ -0,0 +1,27 @@
+## Register provider
+
+The provider must be registered as an `aceProvider`, since there is no point in loading test runner when running your app.
+
+
+```js
+const aceProviders = [
+  '@adonisjs/providers/VowProvider'
+]
+```
+
+## Run tests
+That's all you really need to do in order to get up and running. Now you can run tests by executing following command.
+
+```bash
+adonis test
+```
+
+For help, run
+
+```bash
+adonis test --help
+```
+
+## Envrionment files
+
+The vow provider attempts to load the `.env.test` file when running tests. Any variables placed inside this file will override the actual variables.

templates/unitTest.js

@@ -0,0 +1,7 @@
+'use strict'
+
+const { test } = use('Test/Suite')('Example test suite')
+
+test('dummy test to learn to test 2 + 2', ({ assert }) => {
+  assert.equal(2 + 2, 4)
+})

templates/vowfile.js

@@ -0,0 +1,62 @@
+'use strict'
+
+/*
+|--------------------------------------------------------------------------
+| Vow file
+|--------------------------------------------------------------------------
+|
+| The vow file is loaded before running your tests. This is the best place
+| to hook operations `before` and `after` running the tests.
+|
+*/
+
+// Uncomment when want to run migrations
+// const ace = require('@adonisjs/ace')
+
+module.exports = (cli, runner) => {
+  runner.before(() => {
+    /*
+    |--------------------------------------------------------------------------
+    | Start the server
+    |--------------------------------------------------------------------------
+    |
+    | Starts the http server before running the tests. You can comment this
+    | line, if http server is not required
+    |
+    */
+    use('Adonis/Src/Server').listen()
+
+    /*
+    |--------------------------------------------------------------------------
+    | Run migrations
+    |--------------------------------------------------------------------------
+    |
+    | Migrate the database before starting the tests.
+    |
+    */
+    // await ace.call('migration:run')
+  })
+
+  runner.after(() => {
+    /*
+    |--------------------------------------------------------------------------
+    | Shutdown server
+    |--------------------------------------------------------------------------
+    |
+    | Shutdown the HTTP server when all tests have been executed.
+    |
+    */
+    use('Adonis/Src/Server').getInstance().close()
+
+    /*
+    |--------------------------------------------------------------------------
+    | Rollback migrations
+    |--------------------------------------------------------------------------
+    |
+    | Once all tests have been completed, we should reset the database to it's
+    | original state
+    |
+    */
+    // await ace.call('migration:reset')
+  })
+}