Labs/Jetpack/JEP/28: Difference between revisions

{{Jetpack/Moved to SDK}}
(Added related materials section)
({{Jetpack/Moved to SDK}})
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Jetpack/Moved to SDK}}
== Abstract ==
== Abstract ==


Line 70: Line 72:


In addition to these, the following globals are available to all modules.
In addition to these, the following globals are available to all modules.
=== <tt>__url__</tt> ===
The <tt>__url__</tt> global is a string identifying the URL from which the module or script's code has been retrieved.  If the module or script has no identifiable URL, this value may be <tt>null</tt>.


=== <tt>console</tt> ===
=== <tt>console</tt> ===
Line 138: Line 144:


The following modules come built-in with Cuddlefish and can be retrieved with a call to <tt>require()</tt>.
The following modules come built-in with Cuddlefish and can be retrieved with a call to <tt>require()</tt>.
=== <tt>file</tt> ===
The <tt>file</tt> module provides access to the local filesystem.
<tt>file.'''dirname'''(''path'')</tt>
Returns the path of a file’s containing directory, albeit the parent directory if the file is a directory.
<tt>file.'''list'''(''path'')</tt>
Returns an array of files in the given directory.
<tt>file.'''join'''(''...'')</tt>
Takes a variable number of strings, joins them on the file system’s path separator, and returns the result.


=== <tt>securable-module</tt> ===
=== <tt>securable-module</tt> ===
Line 144: Line 166:


The module's interface is the same as that specified in [[Labs/Jetpack/JEP/25|JEP 25]].
The module's interface is the same as that specified in [[Labs/Jetpack/JEP/25|JEP 25]].
=== <tt>unit-test</tt> ===
The <tt>unit-test</tt> module makes it easy to find and run unit tests.
==== Test Runner Objects ====
Each function which represents a test case is passed a single argument <tt>test</tt>, which represents the test runner.  It has the following methods:
<tt>test.'''pass'''([''message''])</tt>
Marks a test as passing, with the given optional message.
<tt>test.'''fail'''([''message''])</tt>
Marks a test as failing, with the given optional message.
<tt>test.'''exception'''(''e'')</tt>
Marks a test as failing due to the given exception having been thrown.  This can be put in a <tt>catch</tt> clause.
<tt>test.'''assert'''(''a''[, ''message''])</tt>
Ensures that ''a'' has a truthy value.  A test is marked as passing or failing depending on the result, logging ''message'' with it.
<tt>test.'''assertEqual'''(''a'', ''b''[, ''message''])</tt>
Simply ensures that ''a'' <tt>==</tt> ''b'' without recursing into ''a'' or ''b''.  A test is marked as passing or failing depending on the result, logging ''message'' with it.
<tt>test.'''assertNotEqual'''(''a'', ''b''[, ''message''])</tt>
Simply ensures that ''a'' <tt>!=</tt> ''b'' without recursing into ''a'' or ''b''.  A test is marked as passing or failing depending on the result, logging ''message'' with it.
<tt>test.'''assertMatches'''(''string'', ''regexp''[, ''message''])</tt>
Ensures that the given string matches the given regular expression.  If it does, marks a test as passing, otherwise marks a test as failing.  ''message'' is logged with the pass or fail.
<tt>test.'''assertRaises'''(''func'', ''predicate''[, ''message''])</tt>
Calls the function ''func'' with no arguments, expecting an exception to be raised. If nothing is raised, marks the test as failing. If an exception is raised, the exception's <tt>message</tt> property is compared with ''predicate'': if ''predicate'' is a string, then a simple equality comparison is done with <tt>message</tt>. Otherwise, if ''predicate'' is a regular expression, <tt>message</tt> is tested against it. Depending on the outcome, a test is marked as passing or failing, and ''message'' is logged.
<tt>test.'''waitUntilDone'''([''timeout''])</tt>
Puts the test runner into asynchronous testing mode, waiting up to ''timeout'' milliseconds for <tt>test.done()</tt> to be called.  This is intended for use in situations where a test suite schedules a callback, calls <tt>test.waitUntilDone</tt>, and then calls <tt>test.done()</tt> in the callback.
<tt>test.'''done'''()</tt>
Marks a test as being complete.  Assumes a previous call to <tt>test.waitUntilDone()</tt>.
==== Functions ====
<tt>unit-test.'''findAndRunTests'''(''options'')</tt>
''options'' should contain the following properties:
{|cellpadding="5" cellspacing="0" border="1" width="100%"
|<tt>dirs</tt>
|A list of absolute paths representing directories to search for tests in.  It's assumed that all of these directories are also in the module search path, i.e. any JS files found in them are SecurableModules that can be loaded via a call to <tt>require()</tt>.
|-
|<tt>onDone</tt>
|A function to call when testing is complete.
|}
The list of directories is searched for SecurableModules that start with the prefix <tt>test-</tt>.  Each module matching this criteria is expected to export functions that are test cases or a suite of test cases; each is called with a single argument, which is a [[#Test Runner Objects|Test Runner Object]].
=== <tt>xhr</tt> ===
The <tt>xhr</tt> module provides access to <tt>XMLHttpRequest</tt> functionality, also known as AJAX.
<tt>xhr.'''XMLHttpRequest'''()</tt>
Creates an <tt>XMLHttpRequest</tt>. For more information, see [https://developer.mozilla.org/En/Using_XMLHttpRequest Using XMLHttpRequest].
<tt>xhr.'''getRequestCount'''()</tt>
Returns the number of <tt>XMLHttpRequest</tt> objects that are alive (i.e., currently active or about to be).
=== <tt>observer-service</tt> ===
The <tt>observer-service</tt> module provides access to the application-wide observer service singleton.
For a list of common observer topics across a variety of Mozilla-based applications, see [https://developer.mozilla.org/en/Observer_Notifications Observer Notifications].
==== Observer Callbacks ====
Observer callbacks are functions of the following form:
<pre class="brush:js;">
function callback(subject, data) {
  /* Respond to the event notification here... */
}
</pre>
In the above example, <tt>subject</tt> is any JavaScript object, as is <tt>data</tt>.  The particulars of what the two contain are specific to the notification topic.
==== Functions ====
<tt>observer-service.'''add'''(''topic'', ''callback'')</tt>
Adds an observer callback to be triggered whenever a notification matching the string ''topic'' is broadcast throughout the application.
<tt>observer-service.'''remove'''(''topic'', ''callback'')</tt>
Unsubscribes ''callback'' from being triggered whenever a notification matching the string ''topic'' is broadcast throughout the application.
<tt>observer-service.'''notify'''(''topic'', ''subject'', ''data'')</tt>
Broadcasts a notification event with the string ''topic'', passing ''subject'' and ''data'' to all applicable observers in the application.
=== <tt>preferences-service</tt> ===
The <tt>preferences-service</tt> module provides access to the application-wide preferences service singleton.
<tt>preferences-service.'''set'''(''name'', ''value'')</tt>
Sets the application preference ''name'' to ''value''.  ''value'' must be a string, boolean, or number.
<tt>preferences-service.'''get'''(''name'', ''defaultValue'')</tt>
Gets the application preference ''name'', returning ''defaultValue'' if no such preference exists.
<tt>preferences-service.'''has'''(''name'')</tt>
Returns whether or not the application preference ''name'' exists.
<tt>preferences-service.'''isSet'''(''name'')</tt>
Returns whether or not the application preference ''name'' both exists and has been set to a non-default value by the user (or a program acting on the user's behalf).
<tt>preferences-service.'''reset'''(''name'')</tt>
Clears a non-default, user-set value from the application preference ''name''. If no user-set value is defined on ''name'', the function does nothing.


=== <tt>timer</tt> ===
=== <tt>timer</tt> ===
Line 160: Line 314:


The <tt>url</tt> module provides functionality for the parsing and retrieving of URLs.
The <tt>url</tt> module provides functionality for the parsing and retrieving of URLs.
<tt>url.'''toFilename'''(''url'')</tt>
Attempts to convert the given URL to a native file path.  This function will automatically attempt to resolve non-file protocols, such as the <tt>resource:</tt> protocol, to their place on the file system. An exception is raised if the URL can't be converted; otherwise, the native file path is returned as a string.
<tt>url.'''fromFilename'''(''path'')</tt>
Converts the given native file path to a <tt>file:</tt> URL.


<tt>url.'''resolve'''(''base'', ''relative'')</tt>
<tt>url.'''resolve'''(''base'', ''relative'')</tt>
Line 238: Line 400:


Just check out the Mercurial repository and read the [http://hg.mozilla.org/users/avarma_mozilla.com/jep-28/raw-file/tip/README.txt README].
Just check out the Mercurial repository and read the [http://hg.mozilla.org/users/avarma_mozilla.com/jep-28/raw-file/tip/README.txt README].
It's also possible to play around with the latest version of the Minilib in Firefox and Thunderbird using the Cuddlefish Lab extension:
  https://addons.mozilla.org/en-US/firefox/addon/14634/
Once you've installed the extension, just go to the "Tools" menu and select "Cuddlefish Lab" to start experimenting with code.


== Related Materials ==
== Related Materials ==


* [[Labs/Jetpack/JEP/25|JEP 25 - Boosters]]
* [[Labs/Jetpack/JEP/25|JEP 25 - Boosters]]
874

edits