@defra/forms-engine-plugin 1.4.0 → 2.0.0

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

@@ -3,9 +3,13 @@ import { type ResponseToolkit } from '@hapi/hapi'
 
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import {
+  buildFormContextRequest,
+  buildFormRequest
+} from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
+import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import {
   type FormContext,
-  type FormContextRequest,
   type FormPageViewModel,
   type FormState,
   type FormSubmissionState
@@ -51,7 +55,7 @@ describe('QuestionPageController', () => {
     controller1 = new QuestionPageController(model, page1)
     controller2 = new QuestionPageController(model, page2)
 
-    requestPage1 = {
+    requestPage1 = buildFormRequest({
       method: 'get',
       url: page1Url,
       path: page1Url.pathname,
@@ -61,9 +65,9 @@ describe('QuestionPageController', () => {
       },
       query: {},
       app: { model }
-    } as FormRequest
+    } as FormRequest)
 
-    requestPage2 = {
+    requestPage2 = buildFormRequest({
       method: 'get',
       url: page2Url,
       path: page2Url.pathname,
@@ -73,7 +77,7 @@ describe('QuestionPageController', () => {
       },
       query: {},
       app: { model }
-    } as FormRequest
+    } as FormRequest)
   })
 
   describe('Properties', () => {
@@ -289,7 +293,7 @@ describe('QuestionPageController', () => {
         applicantTwoAddress__postcode: 'Postcode'
       }
 
-      let request = {
+      let request = buildFormContextRequest({
         method: 'get',
         url: new URL('http://example.com/test/applicant-one-address'),
         path: '/test/applicant-one-address',
@@ -299,7 +303,7 @@ describe('QuestionPageController', () => {
         },
         query: {},
         app: { model }
-      } satisfies FormContextRequest
+      })
 
       // Calculate our context based on the page we're attempting to load and the above state we provide
       let context = controller.model.getFormContext(request, state)
@@ -331,7 +335,7 @@ describe('QuestionPageController', () => {
       // Now mark that we don't have a UK Passport
       state.ukPassport = false
 
-      request = {
+      request = buildFormContextRequest({
         method: 'get',
         url: new URL('http://example.com/test/summary'),
         path: '/test/summary',
@@ -341,7 +345,7 @@ describe('QuestionPageController', () => {
         },
         query: {},
         app: { model }
-      } satisfies FormContextRequest
+      })
 
       // And recalculate our context
       context = controller.model.getFormContext(request, state)
@@ -375,7 +379,7 @@ describe('QuestionPageController', () => {
 
       const controller = new QuestionPageController(model, pages[0])
 
-      const request = {
+      const request = buildFormContextRequest({
         method: 'get',
         url: new URL('http://example.com/test/page-one'),
         path: '/test/page-one',
@@ -385,7 +389,7 @@ describe('QuestionPageController', () => {
         },
         query: {},
         app: { model }
-      } satisfies FormContextRequest
+      })
 
       const context = controller.model.getFormContext(request, {
         $$__referenceNumber: 'foobar',
@@ -418,7 +422,7 @@ describe('QuestionPageController', () => {
       // The state below shows we said we had a UKPassport and entered details for an applicant
       const state: FormSubmissionState = { $$__referenceNumber: 'foobar' }
 
-      const request = {
+      const request = buildFormContextRequest({
         method: 'get',
         url: new URL('http://example.com/test/page-one'),
         path: '/test/first-page',
@@ -428,7 +432,7 @@ describe('QuestionPageController', () => {
         },
         query: {},
         app: { model }
-      } satisfies FormContextRequest
+      })
 
       const context = controller.model.getFormContext(request, state)
       const evaluationState = { animalType: 'Barn owl' }
@@ -474,7 +478,7 @@ describe('QuestionPageController', () => {
       // The state below shows we said we had a UKPassport and entered details for an applicant
       const state: FormSubmissionState = { $$__referenceNumber: 'foobar' }
 
-      const request = {
+      const request = buildFormContextRequest({
         method: 'get',
         url: new URL('http://example.com/test/page-one'),
         path: '/test/first-page',
@@ -484,7 +488,7 @@ describe('QuestionPageController', () => {
         },
         query: {},
         app: { model }
-      } satisfies FormContextRequest
+      })
 
       const context = controller.model.getFormContext(request, state)
       const evaluationState = { animalType: 'Swan' }
@@ -738,7 +742,7 @@ describe('QuestionPageController V2', () => {
     controller1 = model.pages[0] // new QuestionPageController(model, page1)
     controller2 = model.pages[1] // new QuestionPageController(model, page2)
 
-    requestPage1 = {
+    requestPage1 = buildFormRequest({
       method: 'get',
       url: page1Url,
       path: page1Url.pathname,
@@ -748,9 +752,9 @@ describe('QuestionPageController V2', () => {
       },
       query: {},
       app: { model }
-    } as FormRequest
+    } as FormRequest)
 
-    requestPage2 = {
+    requestPage2 = buildFormRequest({
       method: 'get',
       url: page2Url,
       path: page2Url.pathname,
@@ -760,7 +764,7 @@ describe('QuestionPageController V2', () => {
       },
       query: {},
       app: { model }
-    } as FormRequest
+    } as FormRequest)
   })
 
   describe('Properties', () => {
@@ -973,7 +977,7 @@ describe('QuestionPageController V2', () => {
         applicantTwoAddress__postcode: 'Postcode'
       }
 
-      let request = {
+      let request = buildFormContextRequest({
         method: 'get',
         url: new URL('http://example.com/test/applicant-one-address'),
         path: '/test/applicant-one-address',
@@ -983,7 +987,7 @@ describe('QuestionPageController V2', () => {
         },
         query: {},
         app: { model }
-      } satisfies FormContextRequest
+      })
 
       // Calculate our context based on the page we're attempting to load and the above state we provide
       let context = controller.model.getFormContext(request, state)
@@ -1015,7 +1019,7 @@ describe('QuestionPageController V2', () => {
       // Now mark that we don't have a UK Passport
       state.ukPassport = false
 
-      request = {
+      request = buildFormContextRequest({
         method: 'get',
         url: new URL('http://example.com/test/summary'),
         path: '/test/summary',
@@ -1025,7 +1029,7 @@ describe('QuestionPageController V2', () => {
         },
         query: {},
         app: { model }
-      } satisfies FormContextRequest
+      })
 
       // And recalculate our context
       context = controller.model.getFormContext(request, state)
@@ -1059,7 +1063,7 @@ describe('QuestionPageController V2', () => {
 
       const controller = new QuestionPageController(model, pages[0])
 
-      const request = {
+      const request = buildFormContextRequest({
         method: 'get',
         url: new URL('http://example.com/test/page-one'),
         path: '/test/page-one',
@@ -1069,7 +1073,7 @@ describe('QuestionPageController V2', () => {
         },
         query: {},
         app: { model }
-      } satisfies FormContextRequest
+      })
 
       const context = controller.model.getFormContext(request, {
         $$__referenceNumber: 'foobar',
@@ -1292,7 +1296,7 @@ describe('Save and Return functionality', () => {
 
     controller1 = new QuestionPageController(model, pages[0])
 
-    requestPage1 = {
+    requestPage1 = buildFormRequest({
       method: 'get',
       url: new URL('http://example.com/test/first-page'),
       path: '/test/first-page',
@@ -1302,7 +1306,7 @@ describe('Save and Return functionality', () => {
       },
       query: {},
       app: { model }
-    } as FormRequest
+    } as FormRequest)
   })
 
   const response = {
@@ -1321,7 +1325,9 @@ describe('Save and Return functionality', () => {
 
   describe('shouldShowSaveAndReturn', () => {
     it('should return true by default', () => {
-      expect(controller1.shouldShowSaveAndReturn()).toBe(true)
+      expect(controller1.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+        true
+      )
     })
   })
 

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

@@ -49,6 +49,7 @@ import { merge } from '~/src/server/services/cacheService.js'
 export class QuestionPageController extends PageController {
   collection: ComponentCollection
   errorSummaryTitle = 'There is a problem'
+  allowSaveAndReturn = true
 
   constructor(model: FormModel, pageDef: Page) {
     super(model, pageDef)
@@ -174,7 +175,7 @@ export class QuestionPageController extends PageController {
       showTitle,
       components,
       errors,
-      allowSaveAndReturn: this.shouldShowSaveAndReturn()
+      allowSaveAndReturn: this.shouldShowSaveAndReturn(request.server)
     }
   }
 
@@ -536,10 +537,6 @@ export class QuestionPageController extends PageController {
     return proceed(request, h, nextUrl)
   }
 
-  shouldShowSaveAndReturn(): boolean {
-    return true
-  }
-
   /**
    * Handle save-and-return action by processing form data and redirecting to exit page
    */

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

@@ -1,5 +1,10 @@
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { RepeatPageController } from '~/src/server/plugins/engine/pageControllers/RepeatPageController.js'
+import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
+import {
+  server,
+  serverWithSaveAndReturn
+} from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import {
   type FormContextRequest,
   type FormPageViewModel,
@@ -44,7 +49,7 @@ describe('RepeatPageController', () => {
 
     controller = new RepeatPageController(model, pages[0])
 
-    requestPage = {
+    requestPage = buildFormContextRequest({
       method: 'get',
       url: pageUrl,
       path: pageUrl.pathname,
@@ -54,7 +59,7 @@ describe('RepeatPageController', () => {
       },
       query: {},
       app: { model }
-    }
+    })
 
     requestPageItem = {
       method: 'get',
@@ -66,7 +71,8 @@ describe('RepeatPageController', () => {
         itemId: itemId1
       },
       query: {},
-      app: { model }
+      app: { model },
+      server
     }
 
     requestPageSummary = {
@@ -78,7 +84,8 @@ describe('RepeatPageController', () => {
         slug: 'repeat'
       },
       query: {},
-      app: { model }
+      app: { model },
+      server
     }
   })
 
@@ -263,4 +270,12 @@ describe('RepeatPageController', () => {
       expect(result.errors).toHaveLength(3)
     })
   })
+
+  describe('shouldShowSaveAndReturn', () => {
+    it('should return true when save and return is enabled', () => {
+      expect(controller.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+        true
+      )
+    })
+  })
 })

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

@@ -0,0 +1,32 @@
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { StartPageController } from '~/src/server/plugins/engine/pageControllers/StartPageController.js'
+import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
+import definition from '~/test/form/definitions/basic.js'
+
+describe('StartPageController', () => {
+  let model: FormModel
+  let controller: StartPageController
+
+  beforeEach(() => {
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+
+    // Create a mock page for StartPageController
+    const mockPage = {
+      ...definition.pages[0],
+      controller: 'start'
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    controller = new StartPageController(model, mockPage as any)
+  })
+
+  describe('shouldShowSaveAndReturn', () => {
+    it('should return false (StartPageController does not allow save and return)', () => {
+      expect(controller.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+        false
+      )
+    })
+  })
+})

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

@@ -9,14 +9,12 @@ export class StartPageController extends QuestionPageController {
    * but start pages should really live on gov.uk (whitehall publisher) so a user can be properly signposted.
    */
 
+  allowSaveAndReturn = false
+
   getViewModel(request: FormRequest, context: FormContext) {
     return {
       ...super.getViewModel(request, context),
       isStartPage: true
     }
   }
-
-  shouldShowSaveAndReturn(): boolean {
-    return false
-  }
 }

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

@@ -0,0 +1,32 @@
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { StatusPageController } from '~/src/server/plugins/engine/pageControllers/StatusPageController.js'
+import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
+import definition from '~/test/form/definitions/basic.js'
+
+describe('StatusPageController', () => {
+  let model: FormModel
+  let controller: StatusPageController
+
+  beforeEach(() => {
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+
+    // Create a mock page for StatusPageController
+    const mockPage = {
+      ...definition.pages[0],
+      controller: 'status'
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    controller = new StatusPageController(model, mockPage as any)
+  })
+
+  describe('shouldShowSaveAndReturn', () => {
+    it('should return false (StatusPageController does not allow save and return)', () => {
+      expect(controller.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+        false
+      )
+    })
+  })
+})

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

@@ -9,6 +9,7 @@ import { type FormRequest } from '~/src/server/routes/types.js'
 
 export class StatusPageController extends QuestionPageController {
   declare pageDef: PageStatus
+  allowSaveAndReturn = false
 
   constructor(model: FormModel, pageDef: PageStatus) {
     super(model, pageDef)

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

@@ -68,7 +68,7 @@ export class SummaryPageController extends QuestionPageController {
     viewModel.feedbackLink = this.feedbackLink
     viewModel.phaseTag = this.phaseTag
     viewModel.components = components
-    viewModel.allowSaveAndReturn = this.shouldShowSaveAndReturn()
+    viewModel.allowSaveAndReturn = this.shouldShowSaveAndReturn(request.server)
 
     return viewModel
   }
@@ -144,10 +144,6 @@ export class SummaryPageController extends QuestionPageController {
       }
     }
   }
-
-  shouldShowSaveAndReturn(): boolean {
-    return true
-  }
 }
 
 async function submitForm(

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

@@ -1,5 +1,6 @@
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { TerminalPageController } from '~/src/server/plugins/engine/pageControllers/TerminalPageController.js'
+import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import definition from '~/test/form/definitions/basic.js'
 
 describe('TerminalController', () => {
@@ -25,4 +26,12 @@ describe('TerminalController', () => {
       )
     })
   })
+
+  describe('shouldShowSaveAndReturn', () => {
+    it('should return false (TerminalPageController does not allow save and return)', () => {
+      expect(controller1.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+        false
+      )
+    })
+  })
 })

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

@@ -8,6 +8,7 @@ import { type FormRequestPayload } from '~/src/server/routes/types.js'
 
 export class TerminalPageController extends QuestionPageController {
   declare pageDef: PageTerminal
+  allowSaveAndReturn = false
 
   makePostRouteHandler(): (
     request: FormRequestPayload,

package/src/server/plugins/engine/pageControllers/__stubs__/request.ts

@@ -0,0 +1,21 @@
+import { server } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
+import { type FormContextRequest } from '~/src/server/plugins/engine/types.js'
+import { type FormRequest } from '~/src/server/routes/types.js'
+
+export function buildFormRequest(
+  request: Omit<FormRequest, 'server'>
+): FormRequest {
+  return {
+    ...request,
+    server
+  } as FormRequest
+}
+
+export function buildFormContextRequest(
+  request: Omit<FormContextRequest, 'server'>
+): FormContextRequest {
+  return {
+    ...request,
+    server
+  } as FormContextRequest
+}

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

@@ -0,0 +1,27 @@
+import { type Server } from '@hapi/hapi'
+
+import { type PluginOptions } from '~/src/server/plugins/engine/types.js'
+import { type CacheService } from '~/src/server/services/index.js'
+
+export const server: Server = {
+  plugins: {
+    'forms-engine-plugin': {
+      baseLayoutPath: '',
+      cacheService: {} as CacheService
+    }
+  }
+} as Server // only mocking out properties we care about;
+
+export const serverWithSaveAndReturn: Server = {
+  plugins: {
+    ...server.plugins,
+    'forms-engine-plugin': {
+      ...server.plugins['forms-engine-plugin'],
+      saveAndReturn: {
+        keyGenerator: jest.fn().mockReturnValue('foobar'),
+        sessionHydrator: jest.fn().mockReturnValue({}),
+        sessionPersister: jest.fn().mockImplementation(() => Promise.resolve())
+      } as Pick<PluginOptions, 'saveAndReturn'>
+    }
+  }
+} as Server // only mocking out properties we care about

package/src/server/plugins/engine/plugin.ts

@@ -32,20 +32,19 @@ export const plugin = {
     const {
       model,
       cacheName,
-      keyGenerator,
-      sessionHydrator,
-      sessionPersister,
+      saveAndReturn,
       nunjucks: nunjucksOptions,
       viewContext,
       preparePageEventRequestOptions
     } = options
+
     const cacheService = new CacheService({
       server,
       cacheName,
       options: {
-        keyGenerator,
-        sessionHydrator,
-        sessionPersister
+        keyGenerator: saveAndReturn?.keyGenerator,
+        sessionHydrator: saveAndReturn?.sessionHydrator,
+        sessionPersister: saveAndReturn?.sessionPersister
       }
     })
 
@@ -54,6 +53,7 @@ export const plugin = {
     server.expose('baseLayoutPath', nunjucksOptions.baseLayoutPath)
     server.expose('viewContext', viewContext)
     server.expose('cacheService', cacheService)
+    server.expose('saveAndReturn', saveAndReturn)
 
     server.app.model = model
 

package/src/server/plugins/engine/types.ts

@@ -177,7 +177,10 @@ export type FormContextRequest = (
       payload?: object | undefined
     }
 ) &
-  Pick<FormRequest, 'app' | 'method' | 'params' | 'path' | 'query' | 'url'>
+  Pick<
+    FormRequest,
+    'app' | 'method' | 'params' | 'path' | 'query' | 'url' | 'server'
+  >
 
 export interface UploadInitiateResponse {
   uploadId: string
@@ -305,7 +308,7 @@ export interface FormPageViewModel extends PageViewModelBase {
   context: FormContext
   errors?: FormSubmissionError[]
   hasMissingNotificationEmail?: boolean
-  allowSaveAndReturn?: boolean
+  allowSaveAndReturn: boolean
 }
 
 export interface RepeaterSummaryPageViewModel extends PageViewModelBase {
@@ -363,13 +366,15 @@ export interface PluginOptions {
   cacheName?: string
   globals?: Record<string, GlobalFunction>
   filters?: Record<string, FilterFunction>
-  keyGenerator?: (request: RequestType) => string
-  sessionHydrator?: (request: RequestType) => Promise<FormSubmissionState>
-  sessionPersister?: (
-    key: string,
-    state: FormSubmissionState,
-    request: RequestType
-  ) => Promise<void>
+  saveAndReturn?: {
+    keyGenerator: (request: RequestType) => string
+    sessionHydrator: (request: RequestType) => Promise<FormSubmissionState>
+    sessionPersister: (
+      key: string,
+      state: FormSubmissionState,
+      request: RequestType
+    ) => Promise<void>
+  }
   pluginPath?: string
   nunjucks: {
     baseLayoutPath: string

package/src/server/types.ts

@@ -10,6 +10,7 @@ import { type DetailItem } from '~/src/server/plugins/engine/models/types.js'
 import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
 import {
   type OnRequestCallback,
+  type PluginOptions,
   type PreparePageEventRequestOptions
 } from '~/src/server/plugins/engine/types.js'
 import {
@@ -47,6 +48,7 @@ export interface RouteConfig {
   controllers?: Record<string, typeof PageController>
   preparePageEventRequestOptions?: PreparePageEventRequestOptions
   onRequest?: OnRequestCallback
+  saveAndReturn?: PluginOptions['saveAndReturn']
 }
 
 export interface OutputService {

package/src/typings/hapi/index.d.ts

@@ -5,6 +5,7 @@ import { type ServerYar, type Yar } from '@hapi/yar'
 import { type Logger } from 'pino'
 
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { type PluginOptions } from '~/src/server/plugins/engine/types.ts'
 import {
   type FormRequest,
   type FormRequestPayload
@@ -24,6 +25,7 @@ declare module '@hapi/hapi' {
       viewContext?: (
         request: FormRequest | FormRequestPayload | null
       ) => Record<string, unknown> | Promise<Record<string, unknown>>
+      saveAndReturn?: PluginOptions['saveAndReturn']
     }
   }