feat(testing): Add describeScenario utility to group scenario tests (…

…redwoodjs#9866)

Co-authored-by: Curtis Reimer <51102303+cjreimer@users.noreply.github.com>

__fixtures__/test-project/api/src/services/contacts/describeContacts.scenarios.ts

@@ -0,0 +1,12 @@
+import type { Prisma, Contact } from '@prisma/client'
+
+import type { ScenarioData } from '@redwoodjs/testing/api'
+
+export const standard = defineScenario<Prisma.ContactCreateArgs>({
+  contact: {
+    one: { data: { name: 'String', email: 'String', message: 'String' } },
+    two: { data: { name: 'String', email: 'String', message: 'String' } },
+  },
+})
+
+export type StandardScenario = ScenarioData<Contact, 'contact'>

__fixtures__/test-project/api/src/services/contacts/describeContacts.test.ts

@@ -0,0 +1,57 @@
+import { db } from 'src/lib/db'
+
+import { contact, contacts, createContact } from './contacts'
+import type { StandardScenario } from './contacts.scenarios'
+
+/**
+ * Example test for describe scenario.
+ *
+ * Note that scenario tests need a matching [name].scenarios.ts file.
+ */
+
+describeScenario<StandardScenario>('contacts', (getScenario) => {
+  let scenario: StandardScenario
+
+  beforeEach(() => {
+    scenario = getScenario()
+  })
+
+  it('returns all contacts', async () => {
+    const result = await contacts()
+
+    expect(result.length).toEqual(Object.keys(scenario.contact).length)
+  })
+
+  it('returns a single contact', async () => {
+    const result = await contact({ id: scenario.contact.one.id })
+
+    expect(result).toEqual(scenario.contact.one)
+  })
+
+  it('creates a contact', async () => {
+    const result = await createContact({
+      input: {
+        name: 'Bazinga',
+        email: 'contact@describe.scenario',
+        message: 'Describe scenario works!',
+      },
+    })
+
+    expect(result.name).toEqual('Bazinga')
+    expect(result.email).toEqual('contact@describe.scenario')
+    expect(result.message).toEqual('Describe scenario works!')
+  })
+
+  it('Checking that describe scenario works', async () => {
+    // This test is dependent on the above test. If you used a normal scenario it would not work
+    const contactCreatedInAboveTest = await db.contact.findFirst({
+      where: {
+        email: 'contact@describe.scenario',
+      },
+    })
+
+    expect(contactCreatedInAboveTest.message).toEqual(
+      'Describe scenario works!'
+    )
+  })
+})

docs/docs/testing.md

@@ -1696,6 +1696,107 @@ Only the posts scenarios will be present in the database when running the `posts
 
 During the run of any single test, there is only ever one scenario's worth of data present in the database: users.standard *or* users.incomplete.
 
+### describeScenario - a performance optimisation
+
+The scenario feature described above should be the base starting point for setting up test that depend on the database.  The scenario sets up the database before each scenario _test_, runs the test, and then tears down (deletes) the database scenario.  This ensures that each of your tests are isolated, and that they do not affect each other.
+
+**However**, there are some situations where you as the developer may want additional control regarding when the database is setup and torn down - maybe to run your test suite faster. 
+
+The `describeScenario` function is utilized to run a sequence of multiple tests, with a single database setup and tear-down.
+
+```js
+// highlight-next-line
+describeScenario('contacts', (getScenario) => {
+  // You can imagine the scenario setup happens here
+
+  // All these tests now use the same setup 👇
+  it('xxx', () => {
+    // Notice that the scenario has to be retrieved using the getter
+    // highlight-next-line
+    const scenario = getScenario()
+    //...
+  })
+
+  it('xxx', () => {
+    const scenario = getScenario()
+    /...
+  })
+
+})
+```
+
+> **CAUTION**: With describeScenario, your tests are no longer isolated.  The results, or side-effects, of prior tests can affect later tests.
+
+Rationale for using `describeScenario` include:
+<ul>
+<li>Create multi-step tests where the next test is dependent upon the results of the previous test (Note caution above).</li>
+<li>Reduce testing run time.  There is an overhead to setting up and tearing down the db on each test, and in some cases a reduced testing run time may be of significant benefit.  This may be of benefit where the likelihood of side-effects is low, such as in query testing</li>
+</ul>
+
+### describeScenario Examples
+
+Following is an example of the use of `describeScenario` to speed up testing of a user query service function, where the risk of side-effects is low.
+
+```ts
+// highlight-next-line
+describeScenario<StandardScenario>('user query service', (getScenario) => {
+
+  let scenario: StandardScenario
+
+  beforeEach(() => {
+    // Grab the scenario before each test 
+    // highlight-next-line
+    scenario = getScenario()
+  })
+
+  it('retrieves a single user for a validated user', async () => {
+    mockCurrentUser({ id: 123, name: 'Admin' })
+
+    const record = await user({ id: scenario.user.dom.id })
+
+    expect(record.id).toEqual(scenario.user.dom.id)
+  })
+
+  it('throws an error upon an invalid user id', async () => {
+    mockCurrentUser({ id: 123, name: 'Admin' })
+
+    const fcn = async () => await user({ id: null as unknown as number })
+
+    await expect(fcn).rejects.toThrow()
+  })
+
+  it('throws an error if not authenticated', async () => {
+    const fcn = async () => await user({ id: scenario.user.dom.id })
+
+    await expect(fcn).rejects.toThrow(AuthenticationError)
+  })
+
+  it('throws an error if the user is not authorized to query the user', async () => {
+    mockCurrentUser({ id: 999, name: 'BaseLevelUser' })
+
+    const fcn = async () => await user({ id: scenario.user.dom.id })
+
+    await expect(fcn).rejects.toThrow(ForbiddenError)
+  })
+})
+```
+
+:::tip Using named scenarios with describeScenario
+
+If you have multiple scenarios, you can also use named scenario with `describeScenario`
+
+For example:
+```js
+  // If we have a paymentDeclined scenario defined in the .scenario.{js,ts} file
+  // The second parameter is the name of the "describe" block
+  describeScenario('paymentDeclined', 'Retrieving details',  () => {
+    // ....
+  })
+```
+:::
+
+
+
 ### mockCurrentUser() on the API-side
 
 Just like when testing the web-side, we can use `mockCurrentUser()` to mock out the user that's currently logged in (or not) on the api-side.

packages/internal/src/generate/templates/api-scenarios.d.ts.template

@@ -1,9 +1,10 @@
-import type { Scenario, DefineScenario } from '@redwoodjs/testing/api'
+import type { Scenario, DefineScenario, DescribeScenario } from '@redwoodjs/testing/api'
 
 declare global {
   /**
    * Note that the scenario name must match the exports in your {model}.scenarios.ts file
    */
   const scenario: Scenario
+  const describeScenario: DescribeScenario
   const defineScenario: DefineScenario
 }

packages/testing/config/jest/api/jest.setup.js

@@ -82,8 +82,12 @@ const getProjectDb = () => {
   return db
 }
 
+/**
+ * Wraps "it" or "test", to seed and teardown the scenario after each test
+ * This one passes scenario data to the test function
+ */
 const buildScenario =
-  (it, testPath) =>
+  (itFunc, testPath) =>
   (...args) => {
     let scenarioName, testName, testFunc
 
@@ -96,39 +100,54 @@ const buildScenario =
       throw new Error('scenario() requires 2 or 3 arguments')
     }
 
-    return it(testName, async () => {
-      const path = require('path')
-      const testFileDir = path.parse(testPath)
-      // e.g. ['comments', 'test'] or ['signup', 'state', 'machine', 'test']
-      const testFileNameParts = testFileDir.name.split('.')
-      const testFilePath = `${testFileDir.dir}/${testFileNameParts
-        .slice(0, testFileNameParts.length - 1)
-        .join('.')}.scenarios`
-      let allScenarios, scenario, result
-
-      try {
-        allScenarios = require(testFilePath)
-      } catch (e) {
-        // ignore error if scenario file not found, otherwise re-throw
-        if (e.code !== 'MODULE_NOT_FOUND') {
-          throw e
-        }
+    return itFunc(testName, async () => {
+      let { scenario } = loadScenarios(testPath, scenarioName)
+
+      const scenarioData = await seedScenario(scenario)
+      const result = await testFunc(scenarioData)
+
+      if (wasDbUsed()) {
+        await teardown()
       }
 
-      if (allScenarios) {
-        if (allScenarios[scenarioName]) {
-          scenario = allScenarios[scenarioName]
-        } else {
-          throw new Error(
-            `UndefinedScenario: There is no scenario named "${scenarioName}" in ${testFilePath}.{js,ts}`
-          )
+      return result
+    })
+  }
+
+/**
+ * This creates a describe() block that will seed the scenario ONCE before all tests in the block
+ * Note that you need to use the getScenario() function to get the data.
+ */
+const buildDescribeScenario =
+  (describeFunc, testPath) =>
+  (...args) => {
+    let scenarioName, describeBlockName, describeBlock
+
+    if (args.length === 3) {
+      ;[scenarioName, describeBlockName, describeBlock] = args
+    } else if (args.length === 2) {
+      scenarioName = DEFAULT_SCENARIO
+      ;[describeBlockName, describeBlock] = args
+    } else {
+      throw new Error('describeScenario() requires 2 or 3 arguments')
+    }
+
+    return describeFunc(describeBlockName, () => {
+      let scenarioData
+      beforeAll(async () => {
+        let { scenario } = loadScenarios(testPath, scenarioName)
+        scenarioData = await seedScenario(scenario)
+      })
+
+      afterAll(async () => {
+        if (wasDbUsed()) {
+          await teardown()
         }
-      }
+      })
 
-      const scenarioData = await seedScenario(scenario)
-      result = await testFunc(scenarioData)
+      const getScenario = () => scenarioData
 
-      return result
+      describeBlock(getScenario)
     })
   }
 
@@ -189,6 +208,14 @@ const seedScenario = async (scenario) => {
 
 global.scenario = buildScenario(global.it, global.testPath)
 global.scenario.only = buildScenario(global.it.only, global.testPath)
+global.describeScenario = buildDescribeScenario(
+  global.describe,
+  global.testPath
+)
+global.describeScenario.only = buildDescribeScenario(
+  global.describe.only,
+  global.testPath
+)
 
 /**
  *
@@ -261,8 +288,33 @@ afterAll(async () => {
   }
 })
 
-afterEach(async () => {
-  if (wasDbUsed()) {
-    await teardown()
+function loadScenarios(testPath, scenarioName) {
+  const path = require('path')
+  const testFileDir = path.parse(testPath)
+  // e.g. ['comments', 'test'] or ['signup', 'state', 'machine', 'test']
+  const testFileNameParts = testFileDir.name.split('.')
+  const testFilePath = `${testFileDir.dir}/${testFileNameParts
+    .slice(0, testFileNameParts.length - 1)
+    .join('.')}.scenarios`
+  let allScenarios, scenario
+
+  try {
+    allScenarios = require(testFilePath)
+  } catch (e) {
+    // ignore error if scenario file not found, otherwise re-throw
+    if (e.code !== 'MODULE_NOT_FOUND') {
+      throw e
+    }
   }
-})
+
+  if (allScenarios) {
+    if (allScenarios[scenarioName]) {
+      scenario = allScenarios[scenarioName]
+    } else {
+      throw new Error(
+        `UndefinedScenario: There is no scenario named "${scenarioName}" in ${testFilePath}.{js,ts}`
+      )
+    }
+  }
+  return { scenario }
+}

packages/testing/src/api/scenario.ts

@@ -110,6 +110,10 @@ interface TestFunctionWithScenario<TData> {
   (scenario?: TData): Promise<void>
 }
 
+interface DescribeBlockWithGetScenario<TData> {
+  (getScenario?: () => TData): void
+}
+
 export interface Scenario {
   (title: string, testFunction: TestFunctionWithScenario<any>): void
 }
@@ -126,3 +130,30 @@ export interface Scenario {
 export interface Scenario {
   only: Scenario
 }
+
+export interface DescribeScenario {
+  <TData = any>(
+    title: string,
+    describeBlock: DescribeBlockWithGetScenario<TData>
+  ): void
+}
+
+export interface DescribeScenario {
+  <TData>(
+    title: string,
+    describeBlock: DescribeBlockWithGetScenario<TData>
+  ): void
+}
+
+// Overload for namedScenario
+export interface DescribeScenario {
+  <TData>(
+    namedScenario: string,
+    title: string,
+    describeBlock: DescribeBlockWithGetScenario<TData>
+  ): void
+}
+
+export interface DescribeScenario {
+  only: DescribeScenario
+}