SAMPLE TESTPILOT 2 Study, Showing all features.

tp_2_study.js

/*****************************************
SAMPLE TESTPILOT 2 Study, Showing all features.

== things test pilot can and should do == 

load restartless extension 
unload them
watch, dump, and record events, on XUL and HTML elements
- selectors can be commands, events, types
- actions can be specific things or "*"
surveys
- point to external
- simple, in browser, to be bundled with upload
show / plot user data, with option to opt-out, not send, etc.
snapshotting of any Cu/Cc XPCOM / privileged api  (arbitrary code)
run on subpopulation
- simple default mechanism
- filter based on arbitratrary criteria? 
- allow 'arms' from previous studies to be reused (allowing longitudinal)


== fantasy workflow ==

building a study:
   - turn on firefox
   - do the things I want to monitor, watching them with inspector?
   - see them log somewhere
   
   - tp control panel...? 
      1.  dev a new study... path
      2.  reload the study....
      3.  publish to dev channel

A/B/C....
?Surveys really are gross.  
Notifications.... poke....  jetpack... 


jetpack failures / needs
- notifications
- loading restartless addons (xpcom)
- no official xul modification stuff
- simple storage not big enough

needs:
base_classes: a "which arm am I" function?


basic study skeleton:
---------------
json of metadata
filter (percetct, subgrouping, when)
install some addon from somewhere(url)
watch(selector, evnType)
take_some_snapshot

*****************************************/

/* imports */
StudyBase = require("testpilot-study-base.js");
// put any other cuddlefish imports here....


/* meta data */
exports.experimentInfo = {
    testName                : "Sample and Example Study",
    testId                  : "tp2_example_study",
    summary                 : "Showing the full gamut of things you can do",
    versionNumber           : 1,
    duration                : 14,
    minTPVersion            : "1.0",
    minFXVersion            : "4.0b1",
    recursAutomatically     : false,
    recurrenceInterval      : 60,
    startDate               : null,
    optInRequired           : true,  
}




/* FILTER, who is in the study */
filter = function(callback) {
    /* use any stuff you want in here.  
    *  calls callback with true, if we are running
    */ 
      if (!(locale == "en-US" || locale == "en-CA") ) {
        callback(false);
        return true;
      } else {
        callback(true);
        return true;
      }
};


/*  the meat of the study, showing arms */
onExperimentRun = function(testPilot) {
    // testPilot is a TestPilotAPI() instance
    var tp = testPilot;
    
    var arm;  
    if (tp.arm("some_previous_study")) {
        tp.arm() = 
    }
    
    switch(self.arm())   /* see note */
    {
    case 1:
        ensure_installed("local/url/extension_1.xpi");   /* see note */
        break;
    case 2:
        ensure_installed("local/url/extension_2.xpi");   /* see note */
      break;
    default:
      // code to be executed if n is different from case 1 and 2
    }

    tp.watch('#some-selector','some_event_or_*_or_regex?',callback);
    tp.watch('#some-selector','some_event_or_*_or_regex?',callback);
    tp.watch('#some-selector','some_event_or_*_or_regex?',callback);

    tp.do_snapshot("some branch prefs or state...?", callback?);
    tp.do_snapshot("some branch prefs or state...?", callback?);
    to.do_snapshot("some branch prefs or state...?", callback?);

}


onSubmit?
onFinish?



// GLUE IT ALL TOGETHER
exports.experimentInfo = MyStudy.experimentInfo;
exports.dataStoreInfo = MyStudy.dataStoreInfo;
exports.webContent = MyStudy.webContent;
exports.handlers = MyStudy.handlers;


/*

arm:  property / getter / setter... that gets a pref?  tp.studies.studyname.arm?  Makes it easy
to set by devs.

ensure_installed should be smart enough to register this somewhere, check if it was
 otherwise installed, and do cleanup.
 
*/



//  in the current study stuff

  /* fields required in study description:
   *
   * testName
   * testInfoUrl
   * summary
   * longDescription  (TODO not implemented - would go in webContent I guess??)
   * databaseColumns
   * dataPlotExplanation
   * drawDataPlot
   *
   * optional fields allowed:
   *
   * thumbnailUrl
   * testId (if not present, turn testName into lower_case_with_underscores)
   * version Number  (if not present, is 1)
   * duration (if not present, is 7)
   * recursAutomatically (default: false)
   * recurrenceInterval (default: 60)
   *
   * functions:
   * onAppStartup, onAppShutdown, onExperimentStartup, onExperimentShutdown, getStudyMetadata,
   * filter, doCleanup
   *
   * the functions all get passed a testPilotAPI object that has addListener(), record(), plotGraph()
   *
   * these have never been implemented:
   * startDate (this has never been implemented)
   */