Add DatabaseTestUtils (#988)

* chore: add a quick:test script

* refactor: rename Rollback class

* feat: add DatabaseTestUtils class

* feat(wip): update database provider to register testUtils

* refactor: use test_utils import path

* chore: update @adonisjs/core

* refactor: use resolving for extending testUtils

* refactor: resolve ace only when one of testUtils.db() method is called

* test: check if testUtils.db is registered

* refactor: remove unused ts-expect-error

commands/migration/rollback.ts

@@ -17,7 +17,7 @@ import { CommandOptions } from '@adonisjs/core/types/ace'
  * The command is meant to migrate the database by executing migrations
  * in `down` direction.
  */
-export default class Migrate extends MigrationsBase {
+export default class Rollback extends MigrationsBase {
   static commandName = 'migration:rollback'
   static description = 'Rollback migrations to a specific batch number'
   static options: CommandOptions = {

package.json

@@ -40,6 +40,7 @@
     "test:mssql": "DB=mssql node --enable-source-maps --loader=ts-node/esm ./bin/test.js",
     "test:pg": "DB=pg node --enable-source-maps --loader=ts-node/esm ./bin/test.js",
     "test:docker": "npm run test:mysql && npm run test:mysql_legacy && npm run test:pg && npm run test:mssql",
+    "quick:test": "DB=sqlite node --enable-source-maps --loader=ts-node/esm ./bin/test.js",
     "lint": "eslint . --ext=.ts",
     "clean": "del-cli build",
     "compile": "npm run lint && npm run clean && tsc",
@@ -73,7 +74,7 @@
   },
   "devDependencies": {
     "@adonisjs/assembler": "^7.1.0",
-    "@adonisjs/core": "^6.2.1",
+    "@adonisjs/core": "^6.2.2",
     "@adonisjs/eslint-config": "^1.2.1",
     "@adonisjs/prettier-config": "^1.2.1",
     "@adonisjs/tsconfig": "^1.2.1",
@@ -113,7 +114,7 @@
   },
   "peerDependencies": {
     "@adonisjs/assembler": "^7.0.0",
-    "@adonisjs/core": "^6.2.0",
+    "@adonisjs/core": "^6.2.2",
     "luxon": "^3.4.4"
   },
   "peerDependenciesMeta": {

providers/database_provider.ts

@@ -14,6 +14,7 @@ import { Database } from '../src/database/main.js'
 import { Adapter } from '../src/orm/adapter/index.js'
 import { QueryClient } from '../src/query_client/index.js'
 import { BaseModel } from '../src/orm/base_model/index.js'
+import { DatabaseTestUtils } from '../src/test_utils/database.js'
 import type { DatabaseConfig, DbQueryEventNode } from '../src/types/database.js'
 
 /**
@@ -28,6 +29,12 @@ declare module '@adonisjs/core/types' {
   }
 }
 
+declare module '@adonisjs/core/test_utils' {
+  export interface TestUtils {
+    db(connectionName?: string): DatabaseTestUtils
+  }
+}
+
 /**
  * Extending VineJS schema types
  */
@@ -80,6 +87,19 @@ export default class DatabaseServiceProvider {
     }
   }
 
+  /**
+   * Register TestUtils database macro
+   */
+  protected async registerTestUtils() {
+    this.app.container.resolving('testUtils', async () => {
+      const { TestUtils } = await import('@adonisjs/core/test_utils')
+
+      TestUtils.macro('db', (connectionName?: string) => {
+        return new DatabaseTestUtils(this.app, connectionName)
+      })
+    })
+  }
+
   /**
    * Invoked by AdonisJS to register container bindings
    */
@@ -107,6 +127,7 @@ export default class DatabaseServiceProvider {
     const db = await this.app.container.make('lucid.db')
     BaseModel.$adapter = new Adapter(db)
 
+    await this.registerTestUtils()
     await this.registerReplBindings()
     await this.registerVineJSRules(db)
   }

src/test_utils/database.ts

@@ -0,0 +1,78 @@
+/*
+ * @adonisjs/lucid
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { ApplicationService } from '@adonisjs/core/types'
+
+/**
+ * Database test utils are meant to be used during testing to
+ * perform common tasks like running migrations, seeds, etc.
+ */
+export class DatabaseTestUtils {
+  constructor(
+    protected app: ApplicationService,
+    protected connectionName?: string
+  ) {}
+
+  /**
+   * Runs a command through Ace
+   */
+  async #runCommand(commandName: string, args: string[] = []) {
+    if (this.connectionName) {
+      args.push(`--connection=${this.connectionName}`)
+    }
+
+    const ace = await this.app.container.make('ace')
+    const command = await ace.exec(commandName, args)
+    if (!command.exitCode) return
+
+    if (command.error) {
+      throw command.error
+    } else {
+      throw new Error(`"${commandName}" failed`)
+    }
+  }
+
+  /**
+   * Testing hook for running migrations ( if needed )
+   * Return a function to truncate the whole database but keep the schema
+   */
+  async truncate() {
+    await this.#runCommand('migration:run', ['--compact-output'])
+    return () => this.#runCommand('db:truncate')
+  }
+
+  /**
+   * Testing hook for running seeds
+   */
+  async seed() {
+    await this.#runCommand('db:seed')
+  }
+
+  /**
+   * Testing hook for running migrations
+   * Return a function to rollback the whole database
+   *
+   * Note that this is slower than truncate() because it
+   * has to run all migration in both directions when running tests
+   */
+  async migrate() {
+    await this.#runCommand('migration:run', ['--compact-output'])
+    return () => this.#runCommand('migration:rollback', ['--compact-output'])
+  }
+
+  /**
+   * Testing hook for creating a global transaction
+   */
+  async withGlobalTransaction() {
+    const db = await this.app.container.make('lucid.db')
+
+    await db.beginGlobalTransaction(this.connectionName)
+    return () => db.rollbackGlobalTransaction(this.connectionName)
+  }
+}

test/database_provider.spec.ts

@@ -81,4 +81,39 @@ test.group('Database Provider', () => {
 
     assert.isFalse(db.manager.isConnected('sqlite'))
   })
+
+  test('register testUtils.db() binding', async ({ assert }) => {
+    const ignitor = new IgnitorFactory()
+      .merge({
+        rcFileContents: {
+          providers: [() => import('../providers/database_provider.js')],
+        },
+      })
+      .withCoreConfig()
+      .withCoreProviders()
+      .merge({
+        config: {
+          database: defineConfig({
+            connection: 'sqlite',
+            connections: {
+              sqlite: {
+                client: 'sqlite',
+                connection: { filename: new URL('./tmp/database.sqlite', import.meta.url).href },
+                migrations: { naturalSort: true, paths: ['database/migrations'] },
+              },
+            },
+          }),
+        },
+      })
+      .create(BASE_URL, { importer: IMPORTER })
+
+    const app = ignitor.createApp('web')
+    await app.init()
+    await app.boot()
+
+    const testUtils = await app.container.make('testUtils')
+
+    assert.isDefined(testUtils.db)
+    assert.isFunction(testUtils.db)
+  })
 })