@defra/forms-engine-plugin 2.0.3 → 2.1.0

package/src/server/index.ts

@@ -3,7 +3,8 @@ import { Engine as CatboxRedis } from '@hapi/catbox-redis'
 import hapi, {
   type Request,
   type ResponseToolkit,
-  type ServerOptions
+  type ServerOptions,
+  type ServerRoute
 } from '@hapi/hapi'
 import inert from '@hapi/inert'
 import Scooter from '@hapi/scooter'
@@ -21,7 +22,7 @@ import pluginErrorPages from '~/src/server/plugins/errorPages.js'
 import { plugin as pluginViews } from '~/src/server/plugins/nunjucks/index.js'
 import pluginPulse from '~/src/server/plugins/pulse.js'
 import pluginSession from '~/src/server/plugins/session.js'
-import { publicRoutes } from '~/src/server/routes/index.js'
+import { dummyApiRoutes, publicRoutes } from '~/src/server/routes/index.js'
 import { prepareSecureContext } from '~/src/server/secure-context.js'
 import { type RouteConfig } from '~/src/server/types.js'
 
@@ -120,6 +121,7 @@ export async function createServer(routeConfig?: RouteConfig) {
       name: 'router',
       register: (server) => {
         server.route(publicRoutes)
+        server.route(dummyApiRoutes as ServerRoute[])
       }
     }
   })

package/src/server/plugins/engine/routes/questions.test.ts

@@ -0,0 +1,416 @@
+import Boom from '@hapi/boom'
+import { type ResponseObject, type ResponseToolkit } from '@hapi/hapi'
+// eslint-disable-next-line n/no-unpublished-import
+import nock from 'nock'
+
+import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
+import { redirectOrMakeHandler } from '~/src/server/plugins/engine/routes/index.js'
+import {
+  makeGetHandler,
+  makePostHandler
+} from '~/src/server/plugins/engine/routes/questions.js'
+import { type FormContext } from '~/src/server/plugins/engine/types.js'
+import {
+  type FormRequest,
+  type FormRequestPayload
+} from '~/src/server/routes/types.js'
+jest.mock('~/src/server/plugins/engine/models/SummaryViewModel', () => ({
+  SummaryViewModel: class {
+    summary = 'mocked summary'
+  }
+}))
+
+jest.mock(
+  '~/src/server/plugins/engine/pageControllers/SummaryPageController',
+  () => ({
+    getFormSubmissionData: jest.fn().mockReturnValue([])
+  })
+)
+
+jest.mock('~/src/server/plugins/engine/outputFormatters/machine/v1', () => ({
+  format: jest.fn().mockReturnValue('mocked format')
+}))
+
+jest.mock('~/src/server/plugins/engine/routes/index')
+
+describe('makeGetHandler', () => {
+  const hMock: Pick<ResponseToolkit, 'redirect' | 'view'> = {
+    redirect: jest.fn(),
+    view: jest.fn()
+  }
+
+  beforeEach(() => {
+    nock('http://test').persist().post('/load').reply(200, {
+      wasGetCalled: true
+    })
+  })
+
+  afterEach(() => {
+    jest.mocked(redirectOrMakeHandler).mockRestore()
+    nock.cleanAll()
+  })
+
+  it('calls the callback when events.onLoad.type is http', async () => {
+    let data = {}
+
+    const modelMock = {
+      basePath: 'some-base-path',
+      def: { name: 'Hello world' }
+    } as FormModel
+
+    const pageMock = createMockPageController(
+      modelMock,
+      (
+        _request: FormRequest,
+        context: FormContext,
+        _h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      ) => {
+        data = context.data
+        return Promise.resolve({} as unknown as ResponseObject)
+      }
+    )
+
+    const contextMock = { data: {}, model: {} } as unknown as FormContext
+
+    const requestMock = {
+      params: { path: 'some-path' },
+      app: { model: modelMock }
+    } as FormRequest
+
+    jest
+      .mocked(redirectOrMakeHandler)
+      .mockImplementation(
+        (
+          _req: FormRequest | FormRequestPayload,
+          _h: Pick<ResponseToolkit, 'redirect' | 'view'>,
+          fn
+        ) => Promise.resolve(fn(pageMock, contextMock))
+      )
+
+    await makeGetHandler()(requestMock, hMock)
+
+    expect(data).toMatchObject({
+      wasGetCalled: true
+    })
+  })
+
+  it('does not call the callback when the events.onLoad.type is not http', async () => {
+    let data = {}
+
+    const modelMock = {
+      basePath: 'some-base-path',
+      def: { name: 'Hello world' }
+    } as FormModel
+
+    const pageMock = createMockPageController(
+      modelMock,
+      (
+        _request: FormRequest,
+        context: FormContext,
+        _h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      ) => {
+        data = context.data
+        return Promise.resolve({} as unknown as ResponseObject)
+      }
+    )
+
+    pageMock.events = {}
+
+    const contextMock = { data: {}, model: {} } as unknown as FormContext
+
+    const requestMock = {
+      params: { path: 'some-path' },
+      app: { model: modelMock }
+    } as FormRequest
+
+    jest
+      .mocked(redirectOrMakeHandler)
+      .mockImplementation(
+        (
+          _req: FormRequest | FormRequestPayload,
+          _h: Pick<ResponseToolkit, 'redirect' | 'view'>,
+          fn
+        ) => Promise.resolve(fn(pageMock, contextMock))
+      )
+
+    await makeGetHandler()(requestMock, hMock)
+
+    expect(data).toMatchObject({})
+  })
+
+  it('throws when model is missing', async () => {
+    let error
+
+    const modelMock = {
+      basePath: 'some-base-path',
+      def: { name: 'Hello world' }
+    } as FormModel
+
+    const pageMock = createMockPageController(
+      modelMock,
+      (
+        _request: FormRequest,
+        _context: FormContext,
+        _h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      ) => {
+        return Promise.resolve({} as unknown as ResponseObject)
+      }
+    )
+
+    const contextMock = { data: {}, model: {} } as unknown as FormContext
+
+    const requestMock = {
+      params: { path: 'some-path' },
+      app: {}
+    } as FormRequest
+
+    jest
+      .mocked(redirectOrMakeHandler)
+      .mockImplementation(
+        async (
+          _req: FormRequest | FormRequestPayload,
+          _h: Pick<ResponseToolkit, 'redirect' | 'view'>,
+          fn
+        ) => {
+          try {
+            await fn(pageMock, contextMock)
+          } catch (err) {
+            error = err
+          }
+
+          return Promise.resolve({} as unknown as ResponseObject)
+        }
+      )
+
+    await makeGetHandler()(requestMock, hMock)
+
+    expect(error).toEqual(Boom.notFound('No model found for /some-path'))
+  })
+})
+
+describe('makePostHandler', () => {
+  const hMock: Pick<ResponseToolkit, 'redirect' | 'view'> = {
+    redirect: jest.fn(),
+    view: jest.fn()
+  }
+
+  beforeEach(() => {
+    nock('http://test').post('/save').reply(200, {
+      wasPostCalled: true
+    })
+  })
+
+  afterEach(() => {
+    jest.mocked(redirectOrMakeHandler).mockRestore()
+    nock.cleanAll()
+  })
+
+  it('calls the callback when events.onSave.type is http and the page controller was successful', async () => {
+    const mockPostResponse: ResponseObject = {
+      statusCode: 200
+    } as ResponseObject
+
+    const modelMock = {
+      basePath: 'some-base-path',
+      def: { name: 'Hello world' }
+    } as FormModel
+
+    const pageMock = createMockPageController(
+      modelMock,
+      (
+        _request: FormRequest,
+        _context: FormContext,
+        _h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      ) => {
+        // do return a valid ResponseObject wrapped in Promise.resolve
+        return mockPostResponse
+      }
+    )
+
+    const contextMock = { data: {}, model: {} } as unknown as FormContext
+
+    const requestMock = {
+      params: { path: 'some-path' },
+      app: { model: modelMock },
+      payload: { some: 'payload' }
+    } as unknown as FormRequestPayload
+
+    jest
+      .mocked(redirectOrMakeHandler)
+      .mockImplementation(
+        (
+          _req: FormRequest | FormRequestPayload,
+          _h: Pick<ResponseToolkit, 'redirect' | 'view'>,
+          fn
+        ) => Promise.resolve(fn(pageMock, contextMock))
+      )
+
+    const response = await makePostHandler()(requestMock, hMock)
+
+    expect(nock.pendingMocks()).toBeEmpty()
+    expect(response).toBe(mockPostResponse)
+  })
+
+  it('does not call the callback when the events.onSave.type is not http', async () => {
+    const modelMock = {
+      basePath: 'some-base-path',
+      def: { name: 'Hello world' }
+    } as FormModel
+
+    const pageMock = createMockPageController(
+      modelMock,
+      (
+        _request: FormRequest,
+        _context: FormContext,
+        _h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      ) => {
+        return Promise.resolve({} as unknown as ResponseObject)
+      }
+    )
+
+    pageMock.events = {}
+
+    const contextMock = { data: {}, model: {} } as unknown as FormContext
+
+    const requestMock = {
+      params: { path: 'some-path' },
+      app: { model: modelMock },
+      payload: { some: 'payload' }
+    } as unknown as FormRequestPayload
+
+    jest
+      .mocked(redirectOrMakeHandler)
+      .mockImplementation(
+        (
+          _req: FormRequest | FormRequestPayload,
+          _h: Pick<ResponseToolkit, 'redirect' | 'view'>,
+          fn
+        ) => Promise.resolve(fn(pageMock, contextMock))
+      )
+
+    await makePostHandler()(requestMock, hMock)
+
+    expect(nock.pendingMocks()).not.toBeEmpty()
+  })
+
+  it('does not call the callback when events.onSave.type is http and the page controller was unsuccessful', async () => {
+    const mockPostResponse: ResponseObject = {
+      statusCode: 500
+    } as ResponseObject
+
+    const modelMock = {
+      basePath: 'some-base-path',
+      def: { name: 'Hello world' }
+    } as FormModel
+
+    const pageMock = createMockPageController(
+      modelMock,
+      (
+        _request: FormRequest,
+        _context: FormContext,
+        _h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      ) => {
+        // do return a valid ResponseObject wrapped in Promise.resolve
+        return mockPostResponse
+      }
+    )
+
+    const contextMock = { data: {}, model: {} } as unknown as FormContext
+
+    const requestMock = {
+      params: { path: 'some-path' },
+      app: { model: modelMock },
+      payload: { some: 'payload' }
+    } as unknown as FormRequestPayload
+
+    jest
+      .mocked(redirectOrMakeHandler)
+      .mockImplementation(
+        (
+          _req: FormRequest | FormRequestPayload,
+          _h: Pick<ResponseToolkit, 'redirect' | 'view'>,
+          fn
+        ) => Promise.resolve(fn(pageMock, contextMock))
+      )
+
+    await makePostHandler()(requestMock, hMock)
+
+    expect(nock.pendingMocks()).not.toBeEmpty()
+  })
+
+  it('throws when model is missing', async () => {
+    let error
+
+    const modelMock = {
+      basePath: 'some-base-path',
+      def: { name: 'Hello world' }
+    } as FormModel
+
+    const pageMock = createMockPageController(
+      modelMock,
+      (
+        _request: FormRequest,
+        _context: FormContext,
+        _h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      ) => {
+        return Promise.resolve({} as unknown as ResponseObject)
+      }
+    )
+
+    const contextMock = { data: {}, model: {} } as unknown as FormContext
+
+    const requestMock = {
+      params: { path: 'some-path' },
+      app: {},
+      payload: { some: 'payload' }
+    } as unknown as FormRequestPayload
+
+    jest
+      .mocked(redirectOrMakeHandler)
+      .mockImplementation(
+        async (
+          _req: FormRequest | FormRequestPayload,
+          _h: Pick<ResponseToolkit, 'redirect' | 'view'>,
+          fn
+        ) => {
+          try {
+            await fn(pageMock, contextMock)
+          } catch (err) {
+            error = err
+          }
+
+          return Promise.resolve({} as unknown as ResponseObject)
+        }
+      )
+
+    await makePostHandler()(requestMock, hMock)
+
+    expect(error).toEqual(Boom.notFound('No model found for /some-path'))
+  })
+})
+
+function createMockPageController(
+  model: FormModel,
+  routeHandler: (
+    request: FormRequest,
+    context: FormContext,
+    h: Pick<ResponseToolkit, 'redirect' | 'view'>
+  ) => ResponseObject | Promise<ResponseObject>
+): PageControllerClass {
+  return {
+    model,
+    events: {
+      onLoad: {
+        type: 'http',
+        options: { method: 'POST', url: 'http://test/load' }
+      },
+      onSave: {
+        type: 'http',
+        options: { method: 'POST', url: 'http://test/save' }
+      }
+    },
+    makeGetRouteHandler: () => routeHandler,
+    makePostRouteHandler: () => routeHandler
+  } as unknown as PageControllerClass
+}

package/src/server/plugins/engine/routes/questions.ts

@@ -1,6 +1,7 @@
-import { hasFormComponents, slugSchema } from '@defra/forms-model'
+import { hasFormComponents, slugSchema, type Event } from '@defra/forms-model'
 import Boom from '@hapi/boom'
 import {
+  type ResponseObject,
   type ResponseToolkit,
   type RouteOptions,
   type ServerRoute
@@ -12,14 +13,21 @@ import {
   proceed,
   redirectPath
 } from '~/src/server/plugins/engine/helpers.js'
-import { SummaryViewModel } from '~/src/server/plugins/engine/models/index.js'
+import {
+  SummaryViewModel,
+  type FormModel
+} from '~/src/server/plugins/engine/models/index.js'
 import { format } from '~/src/server/plugins/engine/outputFormatters/machine/v1.js'
 import { getFormSubmissionData } from '~/src/server/plugins/engine/pageControllers/SummaryPageController.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
 import {
   dispatchHandler,
   redirectOrMakeHandler
 } from '~/src/server/plugins/engine/routes/index.js'
-import { type PreparePageEventRequestOptions } from '~/src/server/plugins/engine/types.js'
+import {
+  type FormContext,
+  type PreparePageEventRequestOptions
+} from '~/src/server/plugins/engine/types.js'
 import {
   type FormRequest,
   type FormRequestPayload,
@@ -35,7 +43,36 @@ import {
 } from '~/src/server/schemas/index.js'
 import * as httpService from '~/src/server/services/httpService.js'
 
-function makeGetHandler(
+async function handleHttpEvent(
+  request: FormRequest | FormRequestPayload,
+  page: PageControllerClass,
+  context: FormContext,
+  event: Event,
+  model: FormModel,
+  preparePageEventRequestOptions?: PreparePageEventRequestOptions
+) {
+  const { options } = event
+  const { url } = options
+
+  // TODO: Update structured data POST payload with when helper
+  // is updated to removing the dependency on `SummaryViewModel` etc.
+  const viewModel = new SummaryViewModel(request, page, context)
+  const items = getFormSubmissionData(viewModel.context, viewModel.details)
+
+  // @ts-expect-error - function signature will be refactored in the next iteration of the formatter
+  const payload = format(context, items, model, undefined, undefined)
+  const opts = { payload }
+
+  if (preparePageEventRequestOptions) {
+    preparePageEventRequestOptions(opts, event, page, context)
+  }
+
+  const { payload: response } = await httpService.postJson(url, opts)
+
+  Object.assign(context.data, response)
+}
+
+export function makeGetHandler(
   preparePageEventRequestOptions?: PreparePageEventRequestOptions
 ) {
   return function getHandler(
@@ -59,28 +96,14 @@ function makeGetHandler(
       }
 
       if (events?.onLoad && events.onLoad.type === 'http') {
-        const { options } = events.onLoad
-        const { url } = options
-
-        // TODO: Update structured data POST payload with when helper
-        // is updated to removing the dependency on `SummaryViewModel` etc.
-        const viewModel = new SummaryViewModel(request, page, context)
-        const items = getFormSubmissionData(
-          viewModel.context,
-          viewModel.details
+        await handleHttpEvent(
+          request,
+          page,
+          context,
+          events.onLoad,
+          model,
+          preparePageEventRequestOptions
         )
-
-        // @ts-expect-error - function signature will be refactored in the next iteration of the formatter
-        const payload = format(context, items, model, undefined, undefined)
-        const opts = { payload }
-
-        if (preparePageEventRequestOptions) {
-          preparePageEventRequestOptions(opts, events.onLoad, page, context)
-        }
-
-        const { payload: response } = await httpService.postJson(url, opts)
-
-        Object.assign(context.data, response)
       }
 
       return page.makeGetRouteHandler()(request, context, h)
@@ -88,23 +111,56 @@ function makeGetHandler(
   }
 }
 
-function postHandler(
-  request: FormRequestPayload,
-  h: Pick<ResponseToolkit, 'redirect' | 'view'>
+export function makePostHandler(
+  preparePageEventRequestOptions?: PreparePageEventRequestOptions
 ) {
-  const { query } = request
+  return function postHandler(
+    request: FormRequestPayload,
+    h: Pick<ResponseToolkit, 'redirect' | 'view'>
+  ) {
+    const { query } = request
 
-  return redirectOrMakeHandler(request, h, (page, context) => {
-    const { pageDef } = page
-    const { isForceAccess } = context
+    return redirectOrMakeHandler(request, h, async (page, context) => {
+      const { pageDef } = page
+      const { isForceAccess } = context
+      const { model } = request.app
+      const { events } = page
 
-    // Redirect to GET for preview URL direct access
-    if (isForceAccess && !hasFormComponents(pageDef)) {
-      return proceed(request, h, redirectPath(page.href, query))
-    }
+      // Redirect to GET for preview URL direct access
+      if (isForceAccess && !hasFormComponents(pageDef)) {
+        return proceed(request, h, redirectPath(page.href, query))
+      }
+
+      if (!model) {
+        throw Boom.notFound(`No model found for /${request.params.path}`)
+      }
+
+      const response = await page.makePostRouteHandler()(request, context, h)
+
+      if (
+        events?.onSave &&
+        events.onSave.type === 'http' &&
+        isSuccessful(response)
+      ) {
+        await handleHttpEvent(
+          request,
+          page,
+          context,
+          events.onSave,
+          model,
+          preparePageEventRequestOptions
+        )
+      }
+
+      return response
+    })
+  }
+}
+
+function isSuccessful(response: ResponseObject): boolean {
+  const { statusCode } = response
 
-    return page.makePostRouteHandler()(request, context, h)
-  })
+  return !Boom.isBoom(response) && statusCode >= 200 && statusCode < 400
 }
 
 export function getRoutes(
@@ -174,7 +230,7 @@ export function getRoutes(
     {
       method: 'post',
       path: '/{slug}/{path}/{itemId?}',
-      handler: postHandler,
+      handler: makePostHandler(preparePageEventRequestOptions),
       options: {
         ...postRouteOptions,
         validate: {
@@ -196,7 +252,7 @@ export function getRoutes(
     {
       method: 'post',
       path: '/preview/{state}/{slug}/{path}/{itemId?}',
-      handler: postHandler,
+      handler: makePostHandler(preparePageEventRequestOptions),
       options: {
         ...postRouteOptions,
         validate: {

package/src/server/plugins/engine/services/localFormsService.js

@@ -29,20 +29,19 @@ export const formsService = async () => {
   // Instantiate the file loader form service
   const loader = new FileFormService()
 
-  // Add a Json form
-  await loader.addForm('src/server/forms/register-as-a-unicorn-breeder.json', {
+  // Add a Yaml form
+  await loader.addForm('src/server/forms/register-as-a-unicorn-breeder.yaml', {
     ...metadata,
-    id: '95e92559-968d-44ae-8666-2b1ad3dffd31',
+    id: '641aeafd-13dd-40fa-9186-001703800efb',
     title: 'Register as a unicorn breeder',
     slug: 'register-as-a-unicorn-breeder'
   })
 
-  // Add a Yaml form
-  await loader.addForm('src/server/forms/register-as-a-unicorn-breeder.yaml', {
+  await loader.addForm('src/server/forms/page-events.yaml', {
     ...metadata,
-    id: '641aeafd-13dd-40fa-9186-001703800efb',
-    title: 'Register as a unicorn breeder (yaml)',
-    slug: 'register-as-a-unicorn-breeder-yaml' // if we needed to validate any JSON logic, make it available for convenience
+    id: '511db05e-ebbd-42e8-8270-5fe93f5c9762',
+    title: 'Page events demo',
+    slug: 'page-events-demo'
   })
 
   await loader.addForm('src/server/forms/components.json', {