From 14a850a8190990597018147e0ff2907fa5314db2 Mon Sep 17 00:00:00 2001 From: Curtis Reimer Date: Wed, 13 Dec 2023 21:53:30 -0600 Subject: [PATCH 1/6] started docs development for `defineScenario` --- docs/docs/testing.md | 74 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/docs/docs/testing.md b/docs/docs/testing.md index 12ee3579ad08..962d32fc07a6 100644 --- a/docs/docs/testing.md +++ b/docs/docs/testing.md @@ -1696,6 +1696,80 @@ 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 + +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. However, there are some situations where you as the user may want additional control regarding when the database is setup and torn down. + +The `describeScenario` function is utilized to run a sequence of multiple tests within a single database setup and tear-down. T + +``` +describeScenario('contacts', (getScenario) => { + it('xxx', () => { + // + const scenario = getScenario() + /... + }) + + it('xxx', () => { + // + const scenario = getScenario() + /... + }) + +}) +``` + +> **CAUTION**: With describeScenario, you no long have isolation between tests. The results, or side-effects, of prior tests can affect later tests. + +Rational for using `describeScenario` include: + + +### 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. + +``` +describeScenario('user query service', (getScenario) => { + + it('retrieves a single user for a validated user', async (scenario) => { + mockCurrentUser({ id: 123, name: 'Admin' }) + + const scenario = getScenario() + 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 (scenario) => { + mockCurrentUser({ id: 123, name: 'Admin' }) + + const scenario = getScenario() + const fcn = async () => await user({ id: null as unknown as number }) + + await expect(fcn).rejects.toThrow() + }) + + it('throws an error if not authenticated', async (scenario) => { + const scenario = getScenario() + 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 (scenario) => { + mockCurrentUser({ id: 999, name: 'BaseLevelUser' }) + + const scenario = getScenario() + const fcn = async () => await user({ id: scenario.user.dom.id }) + + await expect(fcn).rejects.toThrow(ForbiddenError) + }) +}) +``` + ### 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. From 29293b9675a1916405d74b7f60a5fa387806ace4 Mon Sep 17 00:00:00 2001 From: Daniel Choudhury Date: Fri, 22 Dec 2023 12:19:16 +0700 Subject: [PATCH 2/6] Update docs/docs/testing.md --- docs/docs/testing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docs/testing.md b/docs/docs/testing.md index 962d32fc07a6..7e6cb8ff9648 100644 --- a/docs/docs/testing.md +++ b/docs/docs/testing.md @@ -1698,7 +1698,9 @@ During the run of any single test, there is only ever one scenario's worth of da ### describeScenario -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. However, there are some situations where you as the user may want additional control regarding when the database is setup and torn down. +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 user may want additional control regarding when the database is setup and torn down. The `describeScenario` function is utilized to run a sequence of multiple tests within a single database setup and tear-down. T From 237c2aedafc32dbd7b186b4cfea96f88602d73dd Mon Sep 17 00:00:00 2001 From: Daniel Choudhury Date: Fri, 22 Dec 2023 12:20:35 +0700 Subject: [PATCH 3/6] Update docs/docs/testing.md --- docs/docs/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/testing.md b/docs/docs/testing.md index 7e6cb8ff9648..3b290d3061a5 100644 --- a/docs/docs/testing.md +++ b/docs/docs/testing.md @@ -1721,7 +1721,7 @@ describeScenario('contacts', (getScenario) => { }) ``` -> **CAUTION**: With describeScenario, you no long have isolation between tests. The results, or side-effects, of prior tests can affect later tests. +> **CAUTION**: With describeScenario, your tests are no longer isolated. The results, or side-effects, of prior tests can affect later tests. Rational for using `describeScenario` include:
    From 9fd7a212c6bddf7de8aeb78d08070110ca249991 Mon Sep 17 00:00:00 2001 From: Daniel Choudhury Date: Fri, 22 Dec 2023 12:21:51 +0700 Subject: [PATCH 4/6] Update docs/docs/testing.md --- docs/docs/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/testing.md b/docs/docs/testing.md index 3b290d3061a5..58a48b7dc365 100644 --- a/docs/docs/testing.md +++ b/docs/docs/testing.md @@ -1696,7 +1696,7 @@ 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 +### 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. From be12cf420466b21d7854d21bfa1eb103e8b95005 Mon Sep 17 00:00:00 2001 From: Daniel Choudhury Date: Fri, 22 Dec 2023 12:24:42 +0700 Subject: [PATCH 5/6] Update docs/docs/testing.md --- docs/docs/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/testing.md b/docs/docs/testing.md index 58a48b7dc365..b0b231053890 100644 --- a/docs/docs/testing.md +++ b/docs/docs/testing.md @@ -1702,7 +1702,7 @@ The scenario feature described above should be the base starting point for setti However, there are some situations where you as the user may want additional control regarding when the database is setup and torn down. -The `describeScenario` function is utilized to run a sequence of multiple tests within a single database setup and tear-down. T +The `describeScenario` function is utilized to run a sequence of multiple tests within a single database setup and tear-down. ``` describeScenario('contacts', (getScenario) => { From d15cf4c1691113c4b63337db7082cdd33dfe6102 Mon Sep 17 00:00:00 2001 From: Daniel Choudhury Date: Mon, 22 Jan 2024 15:28:06 +0700 Subject: [PATCH 6/6] Fix markdown errors --- docs/docs/testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/testing.md b/docs/docs/testing.md index b0b231053890..65f95358ea85 100644 --- a/docs/docs/testing.md +++ b/docs/docs/testing.md @@ -1725,8 +1725,8 @@ describeScenario('contacts', (getScenario) => { Rational for using `describeScenario` include:
      -
    • Create multi-step tests where the next test is dependent upon the results of the previous test (Note caution above). -
    • 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 +
    • Create multi-step tests where the next test is dependent upon the results of the previous test (Note caution above).
      • +
    • 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
    ### describeScenario Examples