refactor(docs-infra): take advantage of latest Jasmine features in preview server tests (#36837)

This commit updates the preview server tests to take advantage of
features supported in the latest version of Jasmine that were not
supported when the rests were first written.

Changes include:

- Use [async/await] in tests.
- Use the new [toBeInstanceOf()] and [toHaveBeenCalledBefore()] matchers.
- Use the new [toBeResolved()] and [toBeRejected()] async matchers (and
  their variants).
- Use the new [withArgs()] method of `Spy` to simplify "trained"
  responses.
- Use the new [resolveTo()]/[rejectWith()] methods of `SpyStrategy` (and
  their variants) to simplify promise-based spies.
- Implement custom async matchers (via [addAsyncMatchers()]) to simplify
  certain tests.

[addAsyncMatchers()]: https://jasmine.github.io/api/3.5/jasmine.html#.addAsyncMatchers
[async/await]: https://jasmine.github.io/tutorials/async
[rejectWith()]: https://jasmine.github.io/api/3.5/SpyStrategy.html#rejectWith
[resolveTo()]: https://jasmine.github.io/api/3.5/SpyStrategy.html#resolveTo
[toBeInstanceOf()]: https://jasmine.github.io/api/3.5/matchers.html#toBeInstanceOf
[toBeRejected()]: https://jasmine.github.io/api/3.5/async-matchers.html#toBeRejected
[toBeResolved()]: https://jasmine.github.io/api/3.5/async-matchers.html#toBeResolved
[toHaveBeenCalledBefore()]: https://jasmine.github.io/api/3.5/matchers.html#toHaveBeenCalledBefore
[withArgs()]: https://jasmine.github.io/api/3.5/Spy.html#withArgs

PR Close #36837

aio/aio-builds-setup/dockerbuild/scripts-js/test/preview-server/jasmine-custom-async-matchers.ts

@@ -0,0 +1,59 @@
+import {PreviewServerError} from '../../lib/preview-server/preview-error';
+
+
+// Matchers
+const toBeRejectedWithPreviewServerError: jasmine.CustomAsyncMatcherFactory = () => {
+  return {
+    async compare(actualPromise: Promise<never>, expectedStatus: number, expectedMessage?: string | RegExp) {
+      if (!(actualPromise instanceof Promise)) {
+        throw new Error(`Expected '${toBeRejectedWithPreviewServerError.name}()' to be called on a promise.`);
+      }
+
+      try {
+        await actualPromise;
+
+        return {
+          pass: false,
+          message: `Expected a promise to be rejected with a '${PreviewServerError.name}', but it was resolved.`,
+        };
+      } catch (actualError) {
+        const actualPrintValue = stringify(actualError);
+        const expectedPrintValue =
+            stringify(new PreviewServerError(expectedStatus, expectedMessage && `${expectedMessage}`));
+
+        const pass = errorMatches(actualError, expectedStatus, expectedMessage);
+        const message =
+            `Expected a promise ${pass ? 'not ' : ''}to be rejected with ${expectedPrintValue}, but is was` +
+            `${pass ? '' : ` rejected with ${actualPrintValue}`}.`;
+
+        return {pass, message};
+      }
+    },
+  };
+
+  // Helpers
+  function errorMatches(actualErr: unknown, expectedStatus: number, expectedMsg?: string | RegExp): boolean {
+    if (!(actualErr instanceof PreviewServerError)) return false;
+    if (actualErr.status !== expectedStatus) return false;
+    return messageMatches(actualErr.message, expectedMsg);
+  }
+
+  function messageMatches(actualMsg: string, expectedMsg?: string | RegExp): boolean {
+    if (typeof expectedMsg === 'undefined') return true;
+    if (typeof expectedMsg === 'string') return actualMsg === expectedMsg;
+    return expectedMsg.test(actualMsg);
+  }
+
+  function stringify(value: unknown): string {
+    if (value instanceof PreviewServerError) {
+      return `${PreviewServerError.name}(${value.status}${value.message ? `, ${value.message}` : ''})`;
+    }
+
+    return jasmine.pp(value);
+  }
+};
+
+// Exports
+export const customAsyncMatchers: jasmine.CustomAsyncMatcherFactories = {
+  toBeRejectedWithPreviewServerError,
+};