Readme.txt

PREREQUISITES: You'll need to download some software onto your Windows machine before running these performance tests:

 * Python 2.4
   The scripts all run from Python 2.4.  You will need the windows version
   (not the cygwin version).  You can download it here:
   http://www.python.org/ftp/python/2.4/python-2.4.msi
   Make sure to correctly set the path to python in the paths.py file.
   After you download and install Python 2.4, you'll need to install
   some extensions:
     * Python Win32 Extensions
       These extensions provide some support for process management and
       performance monitoring.
       http://prdownloads.sourceforge.net/pywin32/pywin32-208.win32-py2.4.exe?download
     * Numerical Python:
       This is required by Matplotlib.
       http://prdownloads.sourceforge.net/numpy/Numeric-24.2.win32-py2.4.exe?download
     * Matplotlib
       This library is used to plot the graphs of performance characteristics
       of Firefox during the page load test.
       http://prdownloads.sourceforge.net/matplotlib/matplotlib-0.87.3.win32-py2.4.exe?download

     * PySyc
       This is used for reading/writing config files in YAML.
       http://pyyaml.org/download/pysyck/PySyck-0.61.2.win32-py2.4.exe

 * Cygwin
   For some reason, we can't get output from Firefox unless it's wrapped in a
   Cygwin sh shell.  So we use cygwin for that, and to sync between Firefox
   runs.  Download it here:
   http://www.cygwin.com/setup.exe

   Make sure to correctly set the path to Cygwin in the paths.py file.

 * msvcp71.dll
   You need a copy of this file to run Python with all the libraries.  If you have
   Visual Studio 2003 installed, you've already got it.

SETUP:

 1. Make sure the prerequisites, above, are installed.
 2. Copy this entire directory and all subdirectories onto your local disk
 3. Edit the paths.py file to set the paths to Cygwin, Firefox, etc. on your 
    machine.
 4. Create a YAML config file with info about the profiles you want to test.
    It should look something like this:

    # Filename will be appended to the timestamp in the report filename.
    # Use letters and underscores only
    filename: slowmachine
    # The title of the report
    title: 1 GHz Celeron

    # Name of profile to test
    Test profile 1:
      # Path to Firefox to test
      firefox: C:\Program Files\Mozilla Firefox 2 Beta 1\firefox.exe

      # Preferences to set in the test (use "preferences : {}" for no prefs)
      preferences:
        javascript.options.showInConsole : true
        xpinstall.enabled : true

      # Extensions to install in test (use "extensions: {}" for none)
      extensions:
        # Need quotes around guid because of curly braces
        "{12345678-1234-1234-1234-abcd12345678}" : c:\path\to\unzipped\xpi
        foo@sample.com : c:\path\to\other\unzipped\xpi

 5. Run run_tests.py with the name of your config file as an argument. You can use
    a space-separated list of config files, to generate a report of startup and page load times. The
    report will be placed in the REPORTS_DIR directory you specified in
    paths.py.

DIRECTORY STRUCTURE:

  page_load_test/
    This directory contains the JavaScript files and html data files for the
    page load test. The page load test opens a new window and cycles through
    loading each html file, timing each load.
  startup_test/
    This directory contains the JavaScript to run the startup test.  It
    measures how long it takes Firefox to start up.
  base_profile/
    This directory contains the base profile used for testing.  A copy of
    this profile is made for each testing profile, and extensions or prefs
    are added according to the test_configs array in run_tests.py.  For the
    page load test to run correctly, the hostperm.1 file must be set to allow
    scheme:file uris to open in new windows, and the pref to force a window
    to open in a tab must not be set.  The dom.allow_scripts_to_close_windows
    pref should also be set to true.  The browser.shell.checkDefaultBrowser
    pref should be set to false.
  run_tests.py, paths.py
    These files should be configured to run the test on different machines,
    with different extensions or preferences.  See setup above.