[POC] Testing utils for SSR Error Handling

[pawelfras]

This PR contains utils that help to test different SSR Error Handling scenarios without redeployment/re-building of the app each time we change the app configuration. It has been achieved by adding a service that reacts to the specific query params which control different behaviours:

export interface TestQueryParams {
  /**
   * Causes HTTP 404 error
   */
  pageNotFoundError?: boolean;
  /**
   * Causes HTTP 500 error
   */
  serverError?: boolean;
  /**
   * Causes error in NgRx flow, that eventually turns into 500 unknown server error
   */
  ngrxError?: boolean;
  /**
   * control `ssrStrictErrorHandlingForHttpAndNgrx` feature toggle. Enabled by default
   */
  enableSsrStrictErrorHandlingForHttpAndNgrx?: boolean;
  /**
   * control `propagateErrorsToServer` feature toggle. Enabled by default
   */
  enablePropagateErrorsToServer?: boolean;
  /** control whether SSR response contains custom status and header:
   * `x-custom-status: 203` and `status: 203`
   */
  customResponseStatus?: boolean;
  /**
   * Causes runtime error in component
   */
  runtimeErrorInComponent?: boolean;

  /**
   * Turn on ExpressJS error handler returning custom error page.
   */
  customErrorPage?: boolean;
}

Config for the fresh and migrated

Prerequisites:

• build and deploy Spartacus packages locally:
  npx ts-node ./tools/schematics/testing.ts in the SPA root folder`
• install packages in the fresh app or the migrated app
  Note: For migrated app, use Angular 17.0.5 because the latest Angular 17 version causes dependencies issue

To use it in a fresh and migrated application, additional adjustments are required:

• in app.component.ts, add the following snippet to be able triggering runtime error in a component:

constructor() {
  if (inject(TestQueryParamsService).queryParams.runtimeErrorInComponent) {
    throw new Error('Runtime error in root component');
  }
}

• in app.module.ts, provide following factories that gives ability to control feature toggles and override endpoints for causing HTTP errors:

    provideFeatureTogglesFactory(() => {
      const {
        enablePropagateErrorsToServer,
        enableSsrStrictErrorHandlingForHttpAndNgrx,
      } = inject(TestQueryParamsService).queryParams;
      return {
        ssrStrictErrorHandlingForHttpAndNgrx:
          enableSsrStrictErrorHandlingForHttpAndNgrx,
        propagateErrorsToServer: enablePropagateErrorsToServer,
      };
    }),
    provideConfigFactory(() => {
      const { pageNotFoundError, serverError } = inject(
        TestQueryParamsService
      ).queryParams;
      return {
        backend: {
          occ: {
            endpoints: {
              pages: pageNotFoundError ? '/cms/pages2' : '/cms/pages',
              components: serverError ? '/cms/components2' : '/cms/components',
            },
          },
        },
      };
    }),

• Last but not least, you need to adjust server.ts file to manipulate ssr optimization options in runtime:

const ngExpressEngine1 = NgExpressEngineDecorator.get(engine, {
  cache: true,
  featureToggles: {
    avoidCachingErrors: true,
  },
})({
  bootstrap: AppServerModule,
});

const ngExpressEngine2 = NgExpressEngineDecorator.get(engine, {
  cache: true,
  shouldCacheRenderingResult: () => true,
  featureToggles: {
    avoidCachingErrors: true,
  },
})({
  bootstrap: AppServerModule,
});

const ngExpressEngine3 = NgExpressEngineDecorator.get(engine, {
  cache: true,
  shouldCacheRenderingResult: () => false,
  featureToggles: {
    avoidCachingErrors: false,
  },
})({
  bootstrap: AppServerModule,
});

const ngExpressEngineDefault = NgExpressEngineDecorator.get(engine)({
  bootstrap: AppServerModule,
});

const ngExpressEngineWrapper = (
  filePath: string,
  options: object,
  callback: any
) => {
  const ngExpressEngineInstance = String(
    (options as any).req.query.ngExpressEngineInstance
  );
  switch (ngExpressEngineInstance) {
    case '1':
      console.log('ngExpressEngineInstance 1');
      return ngExpressEngine1(filePath, options, callback);
    case '2':
      console.log('ngExpressEngineInstance 2');
      return ngExpressEngine2(filePath, options, callback);
    case '3':
      console.log('ngExpressEngineInstance 3');
      return ngExpressEngine3(filePath, options, callback);
    default:
      console.log('ngExpressEngineInstance default');
      return ngExpressEngineDefault(filePath, options, callback);
  }
};

export function app() {
  /* ... */

  //  server.engine(
  //    'html',
  //    ngExpressEngine({
  //      bootstrap: AppServerModule,
  //    })
  //  );
  server.engine('html', ngExpressEngineWrapper);

  /* ... */

  server.use(customErrorPageErrorHandlers); // <--- required to trigger custom error page 
}

How to use it?

Combine chosen query params in the URL regarding the testing scenario, e.g:

http://localhost:4000/electronics-spa/en/USD/?customErrorPage=true&runtimeErrorInComponent=true

to simulate 404 and enable a custom error page which results in the following page:

Note: Query params have to be set each time page is reloaded.

⚠️ Warning: To test whether the app still uses Angular default error handling for runtime errors related to APP_INITIALIZER if SSR Error Handling feature toggles are set to false, all ExpressJS error handlers have to be removed from the server.ts file. I haven't found a way to disable ExpressJS error handlers in runtime (unfortunately if condition inside the error handler isn't enough). That said, an application needs to be rebuilt (and re-deployed in case of testing on CCv2) after the mentioned adjustments in the server file.