@defra/forms-engine-plugin 1.4.0 → 2.0.0

package/src/server/plugins/engine/models/FormModel.test.ts

@@ -6,13 +6,14 @@ import {
 
 import { todayAsDateOnly } from '~/src/server/plugins/engine/date-helper.js'
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
 import { type FormContextRequest } from '~/src/server/plugins/engine/types.js'
 import { V2 as definitionV2 } from '~/test/form/definitions/conditions-basic.js'
 import definition from '~/test/form/definitions/conditions-escaping.js'
 import conditionsListDefinition from '~/test/form/definitions/conditions-list.js'
 import relativeDatesDefinition from '~/test/form/definitions/conditions-relative-dates-v2.js'
 import fieldsRequiredDefinition from '~/test/form/definitions/fields-required.js'
-import joinedConditionsDefinition from '~/test/form/definitions/joined-conditions-test.js'
+import joinedConditionsDefinition from '~/test/form/definitions/joined-conditions-simple-v2.js'
 
 jest.mock('~/src/server/plugins/engine/date-helper.ts')
 
@@ -151,7 +152,7 @@ describe('FormModel', () => {
       }
       const pageUrl = new URL('http://example.com/components/fields-required')
 
-      const request: FormContextRequest = {
+      const request: FormContextRequest = buildFormContextRequest({
         method: 'post',
         payload: { crumb: 'dummyCrumb', action: 'validate' },
         query: {},
@@ -159,7 +160,7 @@ describe('FormModel', () => {
         params: { path: 'components', slug: 'fields-required' },
         url: pageUrl,
         app: { model: formModel }
-      }
+      })
 
       const context = formModel.getFormContext(request, state)
 
@@ -180,7 +181,7 @@ describe('FormModel', () => {
       }
       const pageUrl = new URL('http://example.com/components/fields-required')
 
-      const request: FormContextRequest = {
+      const request: FormContextRequest = buildFormContextRequest({
         method: 'post',
         payload: { crumb: 'dummyCrumb', action: 'validate' },
         query: {},
@@ -188,7 +189,7 @@ describe('FormModel', () => {
         params: { path: 'components', slug: 'fields-required' },
         url: pageUrl,
         app: { model: formModel }
-      }
+      })
 
       expect(() => formModel.getFormContext(request, state)).toThrow(
         'Reference number not found in form state'
@@ -206,7 +207,7 @@ describe('FormModel', () => {
       }
       const pageUrl = new URL('http://example.com/components/fields-required')
 
-      const request: FormContextRequest = {
+      const request: FormContextRequest = buildFormContextRequest({
         method: 'post',
         payload: { crumb: 'dummyCrumb', action: 'validate' },
         query: {},
@@ -214,7 +215,7 @@ describe('FormModel', () => {
         params: { path: 'components', slug: 'fields-required' },
         url: pageUrl,
         app: { model: formModel }
-      }
+      })
 
       expect(() => formModel.getFormContext(request, state)).toThrow(
         'Reference number not found in form state'
@@ -236,14 +237,14 @@ describe('FormModel', () => {
         'http://example.com/conditional-list-items/summary'
       )
 
-      const request: FormContextRequest = {
+      const request: FormContextRequest = buildFormContextRequest({
         method: 'get',
         query: {},
         path: pageUrl.pathname,
         params: { path: 'summary', slug: 'conditional-list-items' },
         url: pageUrl,
         app: { model: formModel }
-      }
+      })
 
       const context = formModel.getFormContext(request, state)
 
@@ -271,14 +272,14 @@ describe('FormModel', () => {
         'http://example.com/conditional-list-items/summary'
       )
 
-      const request: FormContextRequest = {
+      const request: FormContextRequest = buildFormContextRequest({
         method: 'get',
         query: {},
         path: pageUrl.pathname,
         params: { path: 'summary', slug: 'conditional-list-items' },
         url: pageUrl,
         app: { model: formModel }
-      }
+      })
 
       const context = formModel.getFormContext(request, state)
 
@@ -357,15 +358,15 @@ describe('FormModel - Joined Conditions', () => {
     const joinedCondition =
       model.conditions['db43c6bc-9ce6-478b-8345-4fff5eff2ba3']
     expect(joinedCondition).toBeDefined()
-    expect(joinedCondition?.displayName).toBe('joined condition')
+    expect(joinedCondition?.displayName).toBe('is Bob AND over 18')
 
-    const stateAllTrue = { fsZNJr: 'Bob', DaBGpS: true }
+    const stateAllTrue = { userName: 'Bob', isOverEighteen: true }
     expect(joinedCondition?.fn(stateAllTrue)).toBe(true)
 
-    const statePartialTrue = { fsZNJr: 'Alice', DaBGpS: true }
+    const statePartialTrue = { userName: 'Alice', isOverEighteen: true }
     expect(joinedCondition?.fn(statePartialTrue)).toBe(false)
 
-    const stateFalse = { fsZNJr: 'Alice', DaBGpS: false }
+    const stateFalse = { userName: 'Alice', isOverEighteen: false }
     expect(joinedCondition?.fn(stateFalse)).toBe(false)
   })
 
@@ -379,18 +380,92 @@ describe('FormModel - Joined Conditions', () => {
     })
 
     const joinedConditionPage = model.pages.find(
-      (page) => page.path === '/joined-condition-page'
+      (page) => page.path === '/simple-and-page'
     )
 
     expect(joinedConditionPage?.condition).toBeDefined()
 
-    const trueState = { fsZNJr: 'Bob', DaBGpS: true }
+    const trueState = { userName: 'Bob', isOverEighteen: true }
     expect(joinedConditionPage?.condition?.fn(trueState)).toBe(true)
 
-    const falseState = { fsZNJr: 'Bob', DaBGpS: false }
+    const falseState = { userName: 'Bob', isOverEighteen: false }
     expect(joinedConditionPage?.condition?.fn(falseState)).toBe(false)
   })
 
+  it('should handle V1 joined conditions without aliases', () => {
+    formDefinitionV2Schema.validate = jest
+      .fn()
+      .mockReturnValue({ value: definition })
+
+    const model = new FormModel(definition, {
+      basePath: 'test'
+    })
+
+    expect(model.conditions).toBeDefined()
+    expect(Object.keys(model.conditions)).toHaveLength(1)
+
+    const joinedCondition = model.conditions.ZCXeMz
+    expect(joinedCondition).toBeDefined()
+    expect(joinedCondition?.displayName).toBe('test')
+
+    const testState = { NIJphU: "ap'ostrophe's", iraEpG: "shouldn't've" }
+    expect(joinedCondition?.fn(testState)).toBe(true)
+
+    const testStateFalse = { NIJphU: 'other', iraEpG: "shouldn't've" }
+    expect(joinedCondition?.fn(testStateFalse)).toBe(false)
+
+    const context = model.toConditionContext(testState, model.conditions)
+
+    expect(context).not.toHaveProperty('cond_ZCXeMz')
+
+    expect(context).toHaveProperty('ZCXeMz')
+
+    expect(context).toHaveProperty('NIJphU', "ap'ostrophe's")
+    expect(context).toHaveProperty('iraEpG', "shouldn't've")
+  })
+
+  it('should use schema version to determine condition aliases', () => {
+    const v1Definition = { ...definition, schema: SchemaVersion.V1 }
+    formDefinitionV2Schema.validate = jest
+      .fn()
+      .mockReturnValue({ value: v1Definition })
+
+    const v1Model = new FormModel(v1Definition, { basePath: 'test' })
+    expect(v1Model.schemaVersion).toBe(SchemaVersion.V1)
+
+    const v1TestState = { NIJphU: "ap'ostrophe's", iraEpG: "shouldn't've" }
+    const v1Context = v1Model.toConditionContext(
+      v1TestState,
+      v1Model.conditions
+    )
+
+    expect(v1Context).toHaveProperty('ZCXeMz')
+    expect(v1Context).not.toHaveProperty('cond_ZCXeMz')
+
+    formDefinitionV2Schema.validate = jest
+      .fn()
+      .mockReturnValue({ value: joinedConditionsDefinition })
+
+    const v2Model = new FormModel(joinedConditionsDefinition, {
+      basePath: 'test'
+    })
+    expect(v2Model.schemaVersion).toBe(SchemaVersion.V2)
+
+    const v2TestState = { userName: 'Bob', isOverEighteen: true }
+    const v2Context = v2Model.toConditionContext(
+      v2TestState,
+      v2Model.conditions
+    )
+
+    expect(v2Context).toHaveProperty('cond_d15aff7a622440a28e5f51a5af2f7910')
+    expect(v2Context).toHaveProperty('cond_d1f9fcc7f09847e79d314f5ee57ba985')
+    expect(v2Context).toHaveProperty('cond_db43c6bc9ce6478b83454fff5eff2ba3')
+
+    expect(v2Context).not.toHaveProperty('d15aff7a-6224-40a2-8e5f-51a5af2f7910')
+    expect(v2Context).not.toHaveProperty('d1f9fcc7-f098-47e7-9d31-4f5ee57ba985')
+    expect(v2Context).not.toHaveProperty('db43c6bc-9ce6-478b-8345-4fff5eff2ba3')
+  })
+
   describe('generateConditionAlias', () => {
     it('should generate valid JavaScript identifiers from condition IDs', () => {
       formDefinitionV2Schema.validate = jest
@@ -401,7 +476,7 @@ describe('FormModel - Joined Conditions', () => {
         basePath: 'test'
       })
 
-      const evaluationState = { fsZNJr: 'Bob', DaBGpS: true }
+      const evaluationState = { userName: 'Bob', isOverEighteen: true }
 
       const context = model.toConditionContext(
         evaluationState,
@@ -428,8 +503,8 @@ describe('FormModel - Joined Conditions', () => {
         model.conditions['db43c6bc-9ce6-478b-8345-4fff5eff2ba3']
       expect(joinedCondition).toBeDefined()
 
-      const stateTrue = { fsZNJr: 'Bob', DaBGpS: true }
-      const stateFalse = { fsZNJr: 'Alice', DaBGpS: false }
+      const stateTrue = { userName: 'Bob', isOverEighteen: true }
+      const stateFalse = { userName: 'Alice', isOverEighteen: false }
 
       expect(joinedCondition?.fn(stateTrue)).toBe(true)
       expect(joinedCondition?.fn(stateFalse)).toBe(false)

package/src/server/plugins/engine/models/FormModel.ts

@@ -278,9 +278,12 @@ export class FormModel {
     const context = { ...evaluationState }
 
     for (const conditionId in conditions) {
-      const alias = generateConditionAlias(conditionId)
+      const propertyName =
+        this.schemaVersion === SchemaVersion.V2
+          ? generateConditionAlias(conditionId)
+          : conditionId
 
-      Object.defineProperty(context, alias, {
+      Object.defineProperty(context, propertyName, {
         get() {
           return conditions[conditionId]?.fn(evaluationState)
         }

package/src/server/plugins/engine/models/SummaryViewModel.test.ts

@@ -4,6 +4,8 @@ import {
   SummaryViewModel
 } from '~/src/server/plugins/engine/models/index.js'
 import { SummaryPageController } from '~/src/server/plugins/engine/pageControllers/SummaryPageController.js'
+import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
+import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import {
   createPage,
   type PageControllerClass
@@ -14,7 +16,6 @@ import {
   type FormState
 } from '~/src/server/plugins/engine/types.js'
 import definition from '~/test/form/definitions/repeat-mixed.js'
-
 const basePath = `${FORM_PREFIX}/test`
 
 describe('SummaryViewModel', () => {
@@ -36,7 +37,7 @@ describe('SummaryViewModel', () => {
     page = createPage(model, definition.pages[2])
     pageUrl = new URL('http://example.com/repeat/pizza-order/summary')
 
-    request = {
+    request = buildFormContextRequest({
       method: 'get',
       url: pageUrl,
       path: pageUrl.pathname,
@@ -46,7 +47,7 @@ describe('SummaryViewModel', () => {
       },
       query: {},
       app: { model }
-    }
+    })
   })
 
   describe.each([
@@ -272,13 +273,14 @@ describe('SummaryPageController', () => {
         slug: 'repeat'
       },
       query: {},
-      app: { model }
+      app: { model },
+      server: serverWithSaveAndReturn
     }
   })
 
   describe('Save and Return functionality', () => {
     it('should show save and return button on summary page', () => {
-      expect(controller.shouldShowSaveAndReturn()).toBe(true)
+      expect(controller.shouldShowSaveAndReturn(request.server)).toBe(true)
     })
 
     it('should handle save and return from summary page', () => {

package/src/server/plugins/engine/models/SummaryViewModel.ts

@@ -51,7 +51,7 @@ export class SummaryViewModel {
   serviceUrl: string
   hasMissingNotificationEmail?: boolean
   components?: ComponentViewModel[]
-  allowSaveAndReturn?: boolean
+  allowSaveAndReturn = false
 
   constructor(
     request: FormContextRequest,

package/src/server/plugins/engine/options.js

@@ -20,9 +20,11 @@ const pluginRegistrationOptionsSchema = Joi.object({
   preparePageEventRequestOptions: Joi.function().optional(),
   onRequest: Joi.function().optional(),
   baseUrl: Joi.string().uri().required(),
-  keyGenerator: Joi.function().optional(),
-  sessionHydrator: Joi.function().optional(),
-  sessionPersister: Joi.function().optional()
+  saveAndReturn: Joi.object({
+    keyGenerator: Joi.function(),
+    sessionHydrator: Joi.function(),
+    sessionPersister: Joi.function()
+  }).optional()
 })
 
 /**

package/src/server/plugins/engine/options.test.js

@@ -2,6 +2,9 @@ import { validatePluginOptions } from '~/src/server/plugins/engine/options.js'
 
 describe('validatePluginOptions', () => {
   it('returns the validated value for valid options', () => {
+    /**
+     * @type {PluginOptions}
+     */
     const validOptions = {
       nunjucks: {
         baseLayoutPath: 'dxt-devtool-baselayout.html',
@@ -17,6 +20,9 @@ describe('validatePluginOptions', () => {
   })
 
   it('accepts optional properties keyGenerator, sessionHydrator, and sessionPersister', () => {
+    /**
+     * @type {PluginOptions}
+     */
     const validOptionsWithOptionals = {
       nunjucks: {
         baseLayoutPath: 'dxt-devtool-baselayout.html',
@@ -26,9 +32,11 @@ describe('validatePluginOptions', () => {
         return { hello: 'world' }
       },
       baseUrl: 'http://localhost:3009',
-      keyGenerator: () => 'test-key',
-      sessionHydrator: () => Promise.resolve({ someState: 'value' }),
-      sessionPersister: () => Promise.resolve(undefined)
+      saveAndReturn: {
+        keyGenerator: () => 'test-key',
+        sessionHydrator: () => Promise.resolve({ someState: 'value' }),
+        sessionPersister: () => Promise.resolve(undefined)
+      }
     }
 
     expect(validatePluginOptions(validOptionsWithOptionals)).toEqual(
@@ -40,17 +48,20 @@ describe('validatePluginOptions', () => {
    * tsc would usually check compliance with the type, but given a user might be using plain JS we still want a test
    */
   it('fails if a required attribute is missing', () => {
-    // viewContext is missing
-    const invalidOptions = {
-      nunjucks: {
-        baseLayoutPath: 'dxt-devtool-baselayout.html',
-        paths: ['src/server/devserver'] // custom layout to make it really clear this is not the same as the runner
-      }
-    }
+    const invalidOptions =
+      /** @type {PluginOptions} testing without viewContext */ ({
+        nunjucks: {
+          baseLayoutPath: 'dxt-devtool-baselayout.html',
+          paths: ['src/server/devserver'] // custom layout to make it really clear this is not the same as the runner
+        }
+      })
 
-    // @ts-expect-error -- add a test for JS users
     expect(() => validatePluginOptions(invalidOptions)).toThrow(
       'Invalid plugin options'
     )
   })
 })
+
+/**
+ * @import { PluginOptions } from '~/src/server/plugins/engine/types.js'
+ */

package/src/server/plugins/engine/outputFormatters/human/v1.test.ts

@@ -7,7 +7,7 @@ import {
   SummaryPageController,
   getFormSubmissionData
 } from '~/src/server/plugins/engine/pageControllers/SummaryPageController.js'
-import { type FormContextRequest } from '~/src/server/plugins/engine/types.js'
+import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
 import { FormStatus } from '~/src/server/routes/types.js'
 import definition from '~/test/form/definitions/repeat-mixed.js'
 
@@ -52,7 +52,7 @@ const pageUrl = new URL('http://example.com/repeat/pizza-order/summary')
 
 const controller = new SummaryPageController(model, pageDef)
 
-const request = {
+const request = buildFormContextRequest({
   method: 'get',
   url: pageUrl,
   path: pageUrl.pathname,
@@ -62,7 +62,7 @@ const request = {
   },
   query: {},
   app: { model }
-} satisfies FormContextRequest
+})
 
 const context = model.getFormContext(request, state)
 const summaryViewModel = controller.getSummaryViewModel(request, context)

package/src/server/plugins/engine/pageControllers/FileUploadPageController.test.ts

@@ -14,6 +14,7 @@ import {
   prepareStatus
 } from '~/src/server/plugins/engine/pageControllers/FileUploadPageController.js'
 import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import * as pageHelpers from '~/src/server/plugins/engine/pageControllers/helpers.js'
 import * as uploadService from '~/src/server/plugins/engine/services/uploadService.js'
 import {
@@ -31,6 +32,7 @@ import {
   type FormRequest,
   type FormRequestPayload
 } from '~/src/server/routes/types.js'
+import { type CacheService } from '~/src/server/services/index.js'
 import definition from '~/test/form/definitions/file-upload-basic.js'
 
 type TestableFileUploadPageController = FileUploadPageController & {
@@ -77,12 +79,13 @@ describe('FileUploadPageController', () => {
       server: {
         plugins: {
           'forms-engine-plugin': {
+            baseLayoutPath: '',
             cacheService: {
               setFlash: jest.fn(),
               setState: jest
                 .fn()
                 .mockImplementation((req, updated) => Promise.resolve(updated))
-            }
+            } as unknown as CacheService
           }
         }
       },
@@ -1115,4 +1118,12 @@ describe('FileUploadPageController', () => {
       )
     })
   })
+
+  describe('shouldShowSaveAndReturn', () => {
+    it('should return true when save and return is enabled', () => {
+      expect(controller.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+        true
+      )
+    })
+  })
 })

package/src/server/plugins/engine/pageControllers/PageController.test.ts

@@ -3,6 +3,7 @@ import { type ResponseToolkit } from '@hapi/hapi'
 import { FORM_PREFIX } from '~/src/server/constants.js'
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import { type FormRequest } from '~/src/server/routes/types.js'
 import definition from '~/test/form/definitions/basic.js'
 
@@ -230,4 +231,12 @@ describe('PageController', () => {
       )
     })
   })
+
+  describe('shouldShowSaveAndReturn', () => {
+    it('should return false (PageController does not allow save and return)', () => {
+      expect(controller1.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+        false
+      )
+    })
+  })
 })

package/src/server/plugins/engine/pageControllers/PageController.ts

@@ -9,12 +9,14 @@ import Boom from '@hapi/boom'
 import {
   type Lifecycle,
   type ResponseToolkit,
-  type RouteOptions
+  type RouteOptions,
+  type Server
 } from '@hapi/hapi'
 
 import { type ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import {
   encodeUrl,
+  getSaveAndReturnHelpers,
   getStartPath,
   normalisePath
 } from '~/src/server/plugins/engine/helpers.js'
@@ -45,6 +47,7 @@ export class PageController {
   events?: Events
   collection?: ComponentCollection
   viewName = 'index'
+  allowSaveAndReturn = false
 
   constructor(model: FormModel, pageDef: Page) {
     const { def } = model
@@ -183,4 +186,10 @@ export class PageController {
   ) => ReturnType<Lifecycle.Method<FormRequestPayloadRefs>> {
     throw Boom.badRequest('Unsupported POST route handler for this page')
   }
+
+  shouldShowSaveAndReturn(server: Server): boolean {
+    return (
+      getSaveAndReturnHelpers(server) !== undefined && this.allowSaveAndReturn
+    )
+  }
 }