Evaluation Environment - GoogleChromeLabs/ps-analysis-tool GitHub Wiki

What is Evaluation Environment?

An evaluation environment is a controlled testing space designed to isolate the PSAT extension and its interaction with third-party cookies. This environment provides a clean slate, simulating a browser with no prior history or existing cookies.

Why is it important to have an evaluation environment?

Isolation: This environment is completely isolated from your browsing data, like browsing history and cookies. It's like having a newly installed browser without any past activity, ensuring the integrity of the testing process.

Accuracy: By removing external factors like browsing history and cookies, the evaluation environment allows PSAT to focus solely on how third-party cookies function. This reduces the chances of misleading results caused by unrelated browsing activity.

Precision: The controlled environment minimizes distractions and extraneous data, allowing for more precise identification of any issues related to third-party cookies.

How to set up an evaluation environment for PSAT?

Preparing the environment for analyzing and debugging the behavior of cookies and storage APIs during browsing sessions encompasses two aspects: (1) access to Chrome instances with and without Privacy Sandbox APIs enabled and restricted use of third-party cookies; and (2) install PSAT.

Prerequisites

  • The PSAT extension works with modern Chrome versions (Chrome 113+). You can check your Chrome version at chrome://settings/help. For the best experience, keep Chrome updated to the latest stable version.

  • To improve your PSAT debugging experience, please disable Chrome's preloading feature. Navigate to chrome://settings/performance#speed and uncheck "Preload Pages".

Spinning Chrome Instances from Command Line

PSAT's repository includes a set of custom commands streamlining the setup process, by creating ephemeral instances of Google Chrome for Testing with specific configurations (supports switching channels such as Stable, Dev, Canary). To install these commands, run the following in your terminal:

Installation

Run the following command

  1. Download the PSAT Launcher script:
curl -s -f -L "https://raw.githubusercontent.com/GoogleChromeLabs/ps-analysis-tool/main/bin/install.sh" -o "install.sh"
chmod +x install.sh
  1. Install the PSAT Launcher script:
./install.sh
  1. To finalize the installation, close and reopen your terminal, or run source ~/.bashrc or source ~/.zshrc depending on your shell. Alternatively, source the generated launcher script directly:
source "$HOME/bin/chrome_launcher.sh"
  1. To verify the installation, run the following command in your terminal:
chrome-pat-ps

It should open a new Chrome window with the PSAT extension installed and the Privacy Sandbox APIs enabled.

Following options are available to you for installing the PSAT Launcher script:

  1. Override the installation channel: You can specify a different Chrome channel (Stable, Beta, Dev, Canary) by using the --chrome-channel option.

  2. Override the Chrome version: If you want to install a specific version of Chrome, use the --chrome-version option with the desired version number (e.g., 128).

  3. Override the PSAT version: To install a specific version of the PSAT extension, use the --psat-version option with the desired version tag (e.g., v0.14.1).

  4. Uninstall the script: If you want to remove all files created by this script, use the --uninstall option.

  5. Display help message: Use the --help option to see the usage instructions and available options.

./install.sh --help
Usage: ./install.sh [OPTIONS]

Options:
  --chrome-channel CHANNEL    Override the installation channel (Stable, Beta, Dev, Canary)
  --chrome-version VER        Override the Chrome version to be installed (specific milestone number, e.g., 128)
  --psat-version VER          Override the PSAT version to be installed
  --uninstall                 Remove all files created by this script and exit
  --help                      Display this help message and exit

Examples:
  ./install.sh --chrome-channel Beta
  ./install.sh --chrome-version 128
  ./install.sh --psat-version v0.14.1

Once the installation is completed you can use the following commands:

Note: All launcher commands start an isolated, temporary Chrome profile (user-data-dir) and automatically clean it up after the browser window is closed.

  • chrome-default: Opens a Google Chrome for Testing instance with default settings.
  • chrome-3pcd: Opens a Google Chrome for Testing instance with third-party cookies blocked.
  • chrome-default-ps: Opens a Google Chrome for Testing instance with third-party cookies enabled and PSAT installed.
  • chrome-3pcd-ps: Opens a Google Chrome for Testing instance with third-party cookies blocked and PSAT installed.
  • chrome-pat : Opens a Google Chrome for Testing instance with Private Advertising Testing enabled.
  • chrome-pat-ps : Opens a Google Chrome for Testing instance with Private Advertising Testing enabled and the Privacy Sandbox Analysis Tool (PSAT) extension installed.
  • chrome-prt: Opens your locally installed Desktop Google Chrome with IP Protection/PRT features enabled. Optional flags: --stable, --dev, or --canary to manually select the installed channel.

Note about Chrome PRT: IP Protection features are not available on Google Chrome for Testing. For PRT testing, the launcher uses your locally installed Desktop Google Chrome (Stable, Dev, or Canary). Channel selection can be controlled manually via flags: --stable, --dev, or --canary.

Updating the PSAT Launcher script

To keep the Chrome Launcher script current with the latest PSAT Extension, simply rerun the installation command:

  1. Open your terminal.
  2. Run the following command:
curl -s -f -L "https://raw.githubusercontent.com/GoogleChromeLabs/ps-analysis-tool/main/bin/install.sh" -o "install.sh"
chmod +x install.sh
./install.sh
  1. To finalize the update, close and reopen your terminal.

PSAT offers three straightforward installation methods:

Installing PSAT from Chrome Web Store

PSAT is available in the Chrome Web Store ⤴. To install, simply go to the linked store listing and click on Add to Chrome.

Installation from the PSAT zip file

Go to the Releases Section in the PSAT GitHub repo: bit.ly/psat-repo

Select the latest version from the available tags:

Expand the “Assets” dropdown, and click on the file named “extension-v*.*.zip” to download the extension.

Go to chrome://extensions in the browser you want PSAT to be installed on, turn on Developer mode to load the unpacked extension ⤴, click the "Load unpacked" button, and select the unzipped extension folder.

PSAT installation from source code

If you need to debug the extension or submit improvements, you can download the source code and run it locally.

  • Clone this Privacy Sandbox Analysis Tool Repository
  • Run npm install to install all dependencies
  • npm run ext:dev or npm run ext:build to generate a build in /dist/extension
  • Turn on "Developer mode" in chrome://extensions to load the unpacked extension ⤴
  • Click on the "Load Unpacked" button and upload the dist/extension folder