Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

12.0 KB
Raw Blame
/**
 * Copyright (c) Microsoft Corporation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import { kCoverageStashPrefix } from '@isomorphic/istanbulCoverage';
import { parseEvaluationResultValue, serializeAsCallArgument, typedArrayToBase64 } from '@isomorphic/utilityScriptSerializers';

import type { IndexedDBDatabase, OPFSEntry, OriginStorage, SetOriginStorage } from '@protocol/structs';

export type SerializedStorage = Omit<OriginStorage, 'origin'>;

export class StorageScript {
  private _isFirefox: boolean;
  private _global;

  constructor(browserName: string) {
    this._isFirefox = browserName === 'firefox';
    // eslint-disable-next-line no-restricted-globals
    this._global = globalThis;
  }

  private _idbRequestToPromise<T extends IDBOpenDBRequest | IDBRequest>(request: T) {
    return new Promise<T['result']>((resolve, reject) => {
      request.addEventListener('success', () => resolve(request.result));
      request.addEventListener('error', () => reject(request.error));
    });
  }

  private async _directoryEntries(directory: FileSystemDirectoryHandle): Promise<[string, FileSystemHandle][]> {
    // Firefox Xray wrappers expose only string-named WebIDL members, so the async
    // iterator has no Symbol.asyncIterator here ('directory.entries() is not
    // iterable') and `for await` cannot be used. Drive the iterator manually.
    const result: [string, FileSystemHandle][] = [];
    const iterator = directory.entries();
    while (true) {
      const entry = await iterator.next();
      if (entry.done)
        return result;
      result.push(entry.value);
    }
  }

  private _isPlainObject(v: any) {
    const ctor = v?.constructor;
    if (this._isFirefox) {
      const constructorImpl = ctor?.toString() as string | undefined;
      if (constructorImpl?.startsWith('function Object() {') && constructorImpl?.includes('[native code]'))
        return true;
    }
    return ctor === Object;
  }

  private _trySerialize(value: any): { trivial?: any, encoded?: any } {
    let trivial = true;
    const encoded = serializeAsCallArgument(value, v => {
      const isTrivial = (
        this._isPlainObject(v)
        || Array.isArray(v)
        || typeof v === 'string'
        || (typeof v === 'number' && Number.isFinite(v))
        || typeof v === 'boolean'
        || Object.is(v, null)
      );

      if (!isTrivial)
        trivial = false;

      return { fallThrough: v };
    }, { extendedSerialization: true });
    if (trivial)
      return { trivial: value };
    return { encoded };
  }

  private async _collectDB(dbInfo: IDBDatabaseInfo) {
    if (!dbInfo.name)
      throw new Error('Database name is empty');
    if (!dbInfo.version)
      throw new Error('Database version is unset');

    const db = await this._idbRequestToPromise(indexedDB.open(dbInfo.name));
    try {
      if (db.objectStoreNames.length === 0)
        return { name: dbInfo.name, version: dbInfo.version, stores: [] };

      const transaction = db.transaction(db.objectStoreNames, 'readonly');
      const stores = await Promise.all([...db.objectStoreNames].map(async storeName => {
        const objectStore = transaction.objectStore(storeName);

        const keys = await this._idbRequestToPromise(objectStore.getAllKeys());
        const records = await Promise.all(keys.map(async key => {
          const record: IndexedDBDatabase['stores'][0]['records'][0] = {};

          if (objectStore.keyPath === null) {
            const { encoded, trivial } = this._trySerialize(key);
            if (encoded === undefined)
              record.key = trivial;
            else
              record.keyEncoded = encoded;
          }

          const value = await this._idbRequestToPromise(objectStore.get(key));
          const { encoded, trivial } = this._trySerialize(value);
          if (encoded === undefined)
            record.value = trivial;
          else
            record.valueEncoded = encoded;

          return record;
        }));

        const indexes = [...objectStore.indexNames].map(indexName => {
          const index = objectStore.index(indexName);
          return {
            name: index.name,
            keyPath: typeof index.keyPath === 'string' ? index.keyPath : undefined,
            keyPathArray: Array.isArray(index.keyPath) ? index.keyPath : undefined,
            multiEntry: index.multiEntry,
            unique: index.unique,
          };
        });

        return {
          name: storeName,
          records: records,
          indexes,
          autoIncrement: objectStore.autoIncrement,
          keyPath: typeof objectStore.keyPath === 'string' ? objectStore.keyPath : undefined,
          keyPathArray: Array.isArray(objectStore.keyPath) ? objectStore.keyPath : undefined,
        };
      }));

      return {
        name: dbInfo.name,
        version: dbInfo.version,
        stores,
      };
    } finally {
      db.close();
    }
  }

  private async _collectOPFS(root: FileSystemDirectoryHandle): Promise<OPFSEntry[]> {
    const collect = async (directory: FileSystemDirectoryHandle, parentPath: string): Promise<OPFSEntry[]> => {
      const entries = await this._directoryEntries(directory);
      entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);

      const results = await Promise.all(entries.map(async ([name, handle]): Promise<OPFSEntry[]> => {
        const path = parentPath ? `${parentPath}/${name}` : name;
        if (handle.kind === 'directory')
          return [{ path, type: 'directory' }, ...await collect(handle as FileSystemDirectoryHandle, path)];
        const file = await (handle as FileSystemFileHandle).getFile();
        const base64 = typedArrayToBase64(new Uint8Array(await file.arrayBuffer()));
        return [{ path, type: 'file', base64 }];
      }));
      return results.flat();
    };
    return collect(root, '');
  }

  async collect(record: { indexedDB: boolean, opfs: boolean }): Promise<SerializedStorage> {
    const localStorage = Object.keys(this._global.localStorage)
        .filter(name => !name.startsWith(kCoverageStashPrefix))
        .map(name => ({ name, value: this._global.localStorage.getItem(name)! }));
    const result: SerializedStorage = { localStorage };
    if (record.indexedDB) {
      try {
        const databases = await this._global.indexedDB.databases();
        result.indexedDB = await Promise.all(databases.map(db => this._collectDB(db)));
      } catch (e) {
        throw new Error('Unable to serialize IndexedDB: ' + e.message);
      }
    }
    if (record.opfs) {
      try {
        result.opfs = await this._collectOPFS(await this._global.navigator.storage.getDirectory());
      } catch (e) {
        throw new Error('Unable to serialize OPFS: ' + e.message);
      }
    }
    return result;
  }

  private async _restoreDB(dbInfo: IndexedDBDatabase) {
    const openRequest = this._global.indexedDB.open(dbInfo.name, dbInfo.version);
    openRequest.addEventListener('upgradeneeded', () => {
      const db = openRequest.result;
      for (const store of dbInfo.stores) {
        const objectStore = db.createObjectStore(store.name, { autoIncrement: store.autoIncrement, keyPath: store.keyPathArray ?? store.keyPath });
        for (const index of store.indexes)
          objectStore.createIndex(index.name, index.keyPathArray ?? index.keyPath!, { unique: index.unique, multiEntry: index.multiEntry });
      }
    });

    // after `upgradeneeded` finishes, `success` event is fired.
    const db = await this._idbRequestToPromise(openRequest);
    try {
      if (db.objectStoreNames.length === 0)
        return;
      const transaction = db.transaction(db.objectStoreNames, 'readwrite');
      await Promise.all(dbInfo.stores.map(async store => {
        const objectStore = transaction.objectStore(store.name);
        await Promise.all(store.records.map(async record => {
          await this._idbRequestToPromise(
              objectStore.add(
                  'value' in record ? record.value : parseEvaluationResultValue(record.valueEncoded),
                  'key' in record ? record.key : parseEvaluationResultValue(record.keyEncoded),
              )
          );
        }));
      }));
    } finally {
      db.close();
    }
  }

  private async _restoreOPFS(originState: SetOriginStorage | undefined) {
    let root: FileSystemDirectoryHandle;
    try {
      root = await this._global.navigator.storage.getDirectory();
    } catch (e) {
      // OPFS may be unavailable, e.g. on insecure origins or in WebKit contexts
      // that fail with 'unknown transient reason'. There is nothing to clear then,
      // so only fail when there are entries to restore.
      if (originState?.opfs === undefined)
        return;
      throw e;
    }

    await Promise.all((await this._directoryEntries(root)).map(([name]) => root.removeEntry(name, { recursive: true })));

    const entries = originState?.opfs ?? [];
    if (!entries.length)
      return;

    for (const entry of entries) {
      const parts = entry.path.split('/');
      let directory = root;
      for (const part of parts.slice(0, -1))
        directory = await directory.getDirectoryHandle(part, { create: true });

      const name = parts[parts.length - 1];
      if (entry.type === 'directory') {
        await directory.getDirectoryHandle(name, { create: true });
        continue;
      }
      const blob = await this._blobFromBase64(entry.base64!);
      const handle = await directory.getFileHandle(name, { create: true });
      const writable = await handle.createWritable();
      await writable.write(blob);
      await writable.close();
    }
  }

  // Decode through the page's own fetch so that the resulting blob belongs to the page.
  // The Firefox utility world is a sandbox with an extended principal, so the page is
  // denied access to objects allocated here and writing a Uint8Array built in this world
  // fails with 'Permission denied to access property "data"'.
  private async _blobFromBase64(base64: string): Promise<Blob> {
    const response = await this._global.fetch(`data:application/octet-stream;base64,${base64}`);
    return response.blob();
  }

  async restore(originState: SetOriginStorage | undefined) {
    // Clean Service Workers.
    const registrations = this._global.navigator.serviceWorker ? await this._global.navigator.serviceWorker.getRegistrations() : [];
    await Promise.all(registrations.map(async r => {
      // Heuristic for service workers that stalled during main script fetch or importScripts:
      // Waiting for them to finish unregistering takes ages so we do not await.
      // However, they will unregister immediately after fetch finishes and should not affect next page load.
      // Unfortunately, loading next page in Chromium still takes 5 seconds waiting for
      // some operation on this bogus service worker to finish.
      if (!r.installing && !r.waiting && !r.active)
        r.unregister().catch(() => {});
      else
        await r.unregister().catch(() => {});
    }));

    try {
      for (const db of await this._global.indexedDB.databases?.() || []) {
        // Do not wait for the callback - it is called on timer in Chromium (slow).
        if (db.name)
          this._global.indexedDB.deleteDatabase(db.name!);
      }
      await Promise.all((originState?.indexedDB ?? []).map(dbInfo => this._restoreDB(dbInfo)));
    } catch (e) {
      throw new Error('Unable to restore IndexedDB: ' + e.message);
    }

    this._global.sessionStorage.clear();
    this._global.localStorage.clear();
    for (const { name, value } of (originState?.localStorage || []))
      this._global.localStorage.setItem(name, value);

    try {
      await this._restoreOPFS(originState);
    } catch (e) {
      throw new Error('Unable to restore OPFS: ' + e.message);
    }
  }
}