JS and DOM for Gecko Hackers

Quick introduction and disclaimer

I assume webdev familiarity of JS and the DOM

Start by kicking off a build of mozilla-central

Today's objectives

• Write code which uses the new ES6 class-based inheritance
• Examine code which uses old-school prototype-based inheritance
• Understand and use let and for...of
• Array and object destructuring
• Workers
• Promises and Task.jsm
• Arrow functions
• The Browser Toolbox
• Profiling
• Writing a simple WebExtension
• Using a content script in a WebExtension to alter a website
• Debugging an extension
• Testing Gecko
• Writing a "browser chrome" mochitest

Ask questions!

Shiny new ES6 classes

• First shipped in Firefox 45, so this is pretty new stuff
• If you've ever done OOP in other languages, this should feel familiar
• Typical approach for defining a class: class Animal { constructor(sound) { this.sound = sound; } // ^-- no comma speak() { console.log(this.sound); } } let a = new Animal('quack'); a.speak();

Extending, and static class methods

• class Animal { constructor(sound) { this.sound = sound; } speak() { console.log(this.sound); } } class Duck extends Animal { constructor(name) { super("quack"); this.name = name; } greet(who) { console.log(`Hello ${who}, I'm a duck and my name is ${this.name}. ${this.sound}!`); } // We can add a getter for the name here too. static haveSameName(duckA, duckB) { return duckA.name === duckB.name; } } let d1 = new Duck("Howard"); d1.speak(); // d1.greet("Mike"); // let d2 = new Duck("Howard"); // console.log(Duck.haveSameName(d1, d2));

Expect to see more and more of this in the tree.

• For a while, we're going to have two different ways of creating classes in JavaScript in the tree. It's the circle of life.
• Probably best to use this newer style in new, green-field code.
• I've just scratched the surface here. Here's more documentation.

Old-school prototype-based inheritance...

• Usually abstracted away by libraries like Underscore.js or lodash
• Up until recently, this was how you did OOP and inheritance in JavaScript. Lots of Mozilla code still uses this.
• Typical approach for defining a "class": function Animal(sound) { this.sound = sound; } Animal.prototype = { speak() { // ES6 style console.log(this.sound); } }; let a = new Animal('quack'); a.speak();

Prototype-based inheritance...

• Now let's extend this class a bit. function Animal(sound) { this.sound = sound; } Animal.prototype = { speak() { // ES6 style console.log(this.sound); } }; function Duck(name) { Animal.call(this, "quack"); this.name = name; } Duck.prototype = Object.create(Animal.prototype); Duck.prototype.greet = function(who) { console.log(`Hello ${who}, I'm a duck and my name is ${this.name}. ${this.sound}!`); // I'm using a ES6 template string here --^ } let d = new Duck("Howard"); d.speak(); //d.greet("Mike"); // Now let's do stuff with getters (get name(), and Object.create) // Also, instanceof - though instanceof can be easily fooled
• On inheritance in Javascript.
• JS OOP gotchas, and an argument against inheritance.

let

• Here's a link to some more comprehensive documentation
• In the beginning, there was var. And it was alright... but there are some interesting gotchas.
• var is function scoped, whereas let is block scoped. (function scope() { var baz = "Plz don't overwrite me." { // <-- this could be a block for a conditional, a loop, etc... var baz = "blam!"; console.log(baz); } console.log(baz); }()); // This has interesting consequences for for-loop binding // doing async things - example: /* for (var i = 0; i < 3; ++i) { setTimeout(function() { console.log(i); }, 50); }*/
• Other gotchas... // var's can be redeclared in the same block scope, whereas let's cannot. { var x = 1; var x = 2; } // var hoists! let does not. /* (function() { console.log(myVariable); var myVariable = "The above will result in undefined, not a ReferenceError"; }()); */

let

for...of

• for, for...in, forEach
• for...of is great for iterable objects like Arrays, Maps, Sets, and anything exposing Symbol.iterator as a property
• Object property iteration still done with for...in
• Example: //let x = [1, 2, 3]; /* let candies = new Set(); candies.add('chocolate'); candies.add('gum');*/ //let candies = {chocolate: '90% dark', gum: 'Everlasting freshness'}; // Won't work // Maps with decomposition: for (let [key, value] of someMap)... for (let candy of candies) { console.log(candy); }
• Generally speaking, for...of is probably the way you want to iterate, except for Object properties

Object and Array destructuring

• Fancy shorthand for multi-variable assignment
• Useful if you have a function that returns an Object or an Array that you only want a part of.
• Example: function mikesPage() { return { url: 'http://www.mikeconley.ca', type: 'blog' }; } let { url } = mikesPage(); console.log(url); let { url: someURL } = mikesPage(); console.log(someURL); // Gotcha: I can do let reassignment in block scope with destructuring. Fun times! // Arrays...

Object and Array destructuring

• Also useful when a function accepts an Object function myFunction({ firstArg, secondArg }) { console.log(`First arg: ${firstArg}, secondArg: ${secondArg}`); } myFunction({ firstArg: "This is first!", secondArg: "This is second!", });
• Common pattern:

              const { classes: Cc, interfaces: Ci, utils: Cu } = Components;
              // ^-- oh yeah, const...
            

• Lots of other examples right here
• Documentation on const

Whew!

• Hopefully we're about 1 hour in, or thereabouts.
• Let's hear some questions, and do some exercises. function Shape({ x, y }) { this._x = x; this._y = y; } Shape.prototype = { get coords() { return { x: this._x, y: this._y }; }, } // Implement Rect, which subclasses Shape. In addition to // the x and y coordinate parameters, should also take height // and width. Should also have a isSquare getter that returns // true if the Rect is square. let s = new Rect({ x: 5, y: 5, h: 25, w: 25 }); console.log(s.isSquare); /* let rects = [ new Rect({ x: 0, y: 0, h: 5, w: 100 }), new Rect({ x: 0, y: 5, h: 13, w: 2 }), new Rect({ x: 10, y: 10, h: 15, w: 15 }), new Rect({ x: 16, y: -5, h: 3, w: 3 }), ]; // Iterate the rects using for...of, and console.log // isSquare for each. */ /* // Using object destructuring to assign the coords of // s to local variables x and y in a single line. */

Asynchronicity and Concurrency

Asynchronous things in JavaScript

• JavaScript is single-threaded and event driven
• "Asynchronous" things queue a function to fire at a later time, but still on the main thread
• One can use setTimeout to break up heavy work into chunks, but there are better ways

Workers

• Moving process-heavy things off the main thread is good for responsiveness
• Workers allow actual concurrency in JavaScript, with some limitations (the main one being the DOM)
• Here's a full list of things available to Workers in Firefox
• function workerFunc() { var d = Date.now(); console.log("Starting..."); while(Date.now() - d < 2000) {} console.log("Done waiting 2 seconds!"); /* ^-- this will output to the devtools console */ } let w = new Worker(`data:,(${workerFunc.toString()})();`); // Normally workers are defined in separate scripts, like this: // let w = new Worker("some_worker.js");

Communicating with Workers

• Communication is done with message passing
• You can't send a function over unless you somehow eval it on the other side
• But if it can be serialized to JSON, then it can be sent
• Here's worker_example_1.js:

Communicating with Workers

• Let's use that file... let w = new Worker("examples/worker_example_1.js"); w.addEventListener("message", function(e) { if (e.data.name == "Log") { console.log(e.data.msg); } }); w.postMessage(2);

ChromeWorkers

• Extends Workers with more powers, and ES6 stuff (like let)
• Non-standard, and not exposed to web content
• Has access to js-ctypes via a global ctypes.

Promises

• Asynchronous code can result in callback hell: function doAsyncThing(arg, callback) { return doFirstPart(arg, function(result1) { doSecondPart(result1, function(result2) { doLastPart(result2, function(result3) { callback(result3); }); }); }); }
• You still see this pattern in older parts of our code, like old tests

Promises

• Promises reorient things by adding an intermediary "then-able" object
• Difference is subtle, but the results can be profound
• If doFirstPart, doSecondPart and doLastPart returned Promises, we could do: function doAsyncThing(arg) { let promise = doFirstPart(arg); return promise.then(doSecondPart) .then(doLastPart) .catch(console.error); }
• That might seem like a small win, but it gets better with yield and Tasks

Promises

• Let's write a function that returns a Promise function sleep(aMs) { return new Promise(function(resolve, reject) { if (aMs < 0) { reject("Can't sleep for negative time."); return; } setTimeout(function() { resolve("All done"); }, aMs * 1000); // This can be one-liner'd... }); } sleep(2).then(function(msg) { console.log(msg); }).catch(function(msg) { console.log("ERROR: " + msg); });
• Questions about Promises? Because we're about to crank it up...

Tasks

• ES6 gives us the yield keyword
• Used for Generators, allows us to effectively halt and resume a function
• Coupled with Promises, this leads us to Tasks!
• Not sure how often they're used on the web, but used extensively in Firefox function sleep(aMs) { return new Promise(function(resolve, reject) { if (aMs < 0) { reject("Can't sleep for negative time."); return; } setTimeout(function() { resolve("All done"); }, aMs * 1000); // This can be one-liner'd... }); } Task.spawn(function() { // Should be function*, but that doesn't work with Task.js console.log("Starting to sleep for seconds"); yield sleep(2); console.log("Done first sleep - now for second sleep"); yield sleep(2); console.log("Done sleeping. We're done, folks!"); });
• This was task.js, not Task.jsm, because this slideshow is in web content

Task.jsm

• Available as a JSM at resource://gre/modules/Task.jsm
• Control flow and error handling example: // This won't run in here - paste it into a Scratchpad in the // Browser Environment Components.utils.import("resource://gre/modules/Task.jsm"); function sleep(aMs) { return new Promise(function(resolve, reject) { if (aMs < 0) { reject("Can't sleep for negative time."); return; } setTimeout(resolve, aMs * 1000); // One-liner'd! }); } Task.spawn(function*() { console.log("Starting to sleep for seconds"); yield sleep(2); console.log("Done first sleep - now for second sleep"); yield sleep(2); console.log("Done sleeping. We're done, folks!"); return "Success!"; }).then(function(msg) { console.log("All done! Result: " + msg); }).catch(function(e) { console.log("RUH ROH: " + e); });

Arrow functions

• Sometimes you're not in a position to use Tasks, so you need to pass a callback to a Promise's then() function.
• When you're doing this inside an Object method, it's often useful for the callback to bind this to the Object
• Before arrow functions, there were several ways to do this: var Duck = { asyncQuack: function() { this.sleep(100).then(function() { try { this.quack(); // This will not work! } catch(e) { console.log(e.message); } }, 5000); }, quack: function() { console.log("Quack"); }, sleep: function(aMs) { return new Promise(function(resolve) { setTimeout(resolve, aMs); }) } }; Duck.asyncQuack(); // One work around is to alias this in the closure... // Another is to use .bind... // But my favourite is the arrow function, which automatically binds "this" to the enclosing context! // Also handy for quick functions. /* let x = [{ name: "Mike", pumpkins: 1 }, { name: "Emily", pumpkins: 12 }, { name: "Cassie", pumpkins: 3 }]; console.log(x.filter(function(person) { return person.pumpkins > 3; }));*/

Whew!

• Hopefully we're about 2 hours in, or thereabouts (if not, we're in trouble, and I need to move faster).
• Let's hear some questions, and do some exercises. // Let's re-use examples/worker_example_1.js, and create a function sleep that // instead of using setTimeout, sends a message to the worker, and returns // a Promise that resolves when the Worker responds with the "Done" message. let w = new Worker("examples/worker_example_1.js"); // Then, let's write a Task that yields some sleeps. Again, we can't // use Task.jsm in here, so we're using task.js, which is similar.

Browser Tools and Extension-writing

The Browser Toolbox

• If you didn't already know, Firefox's UI ("chrome") uses the same rendering and JS engine as web content
• This means that our web developer tools are re-usable for the Firefox UI!
• The ability to inspect, manipulate and debug chrome code is disabled by default

A Tour of the Browser Toolbox

Writing a WebExtension

A brief introduction to WebExtensions

• These are brand-spankin' new, and not released yet.
• Modeled after the Chromium extension APIs
• Multiprocess friendly by default!
• We're close to API parity, and we're hoping to add APIs and augment existing ones.

• mkdir my-webextension
  cd my-webextension
  # Use your editor, and open a new file called manifest.json
  

manifest.json

• This is where your WebExtension describes itself
• Here's some boilerplate for you:

  {
    "name": "My WebExtension",
    "version": "1.0",
    "manifest_version": 2,
    "description": "Tooling around with WebExtensions",
    "permissions": [],
  
    "applications": {
      "gecko": {
        "id": "my-webextension@webextensions"
      }
    }
  }
  

• Let's run it!
• It's installed, but it's boring. Let's do something neat...

Modifying pages with content scripts...

• Content scripts are injected into web content, and get an X-ray view of the DOM and JS environment of a page
• They have limited privileges, but can communicate things to the parent process where there are elevated privileges
• Open up manifest.json again... "content_scripts": [ { "matches": ["*://*.mozilla.org/*"], "js": ["content.js"], "run_at": "document_idle" } ],

Now our content script...

• let h1 = document.createElement("h1"); h1.style.color = "red"; h1.textContent = "Oh, hello there!"; document.body.insertBefore(h1, document.body.firstChild);

Debugging

Packaging and signing

• Firefox add-ons are XPI files, which are really just ZIP files
• ZIP up the contents of that folder we just made, and you've got an (unsigned) add-on
• xpinstall.signatures.required
• You can sign an add-on using the jpm tool, or by uploading to AMO.

Automated tests

We use a number of test frameworks

• My guess is that we discover that the existing framework is insufficient so we build a new one and never fully migrate
• There are other reasons - like we might want some tests to be cross-browser compatible
• Regardless, we have several different "types" of tests

Our testing frameworks:

• xpcshell: This test runs in a JavaScript "shell" with XPCOM access. No windows, and no DOM. Good for testing JS, or bits that don't require DOM.
• reftests: Tests that do some layout and / or rendering, which we then compare against a reference image. Good for testing graphics and layout.
• mochitest-plain: Tests web content with web content privleges. Good for testing for compliance with web specs.
• mochitest-chrome: Privileged tests running in a bare window. Good for testing XUL and layout.
• mochitest-browser: Privileged tests running in a browser. Good for exercising Firefox to do Firefox things.
• marionette: Our newest browser automation framework. Similar to Selenium. Can drive Firefox for Desktop, as well as B2G. This is probably the future.
• wpt: Similar to mochitest-plain, but actually being used between browsers (like Firefox and Servo).
• Here's a decision chart to help you determine which one you should use when.

How to run tests

./mach test [path-to-test]

./mach test browser/base/content/test/general/browser_audioTabIcon.js
#       ^-- This will automatically choose the right framework,
#           and is good if you just want to run the test simply.

# Note also that the test starts with browser_. This is a browser mochitest.
# xpcshell, mochitest-plain and mochitest-chrome start with test_.

./mach mochitest browser/base/content/test/general/browser_audioTabIcon.js

# Functionally equivalent to the first one

./mach mochitest browser/base/content/test/general/browser_audioTabIcon.js --disable-e10s

# --disable-e10s = Run without out-of-process tabs

# Check out --help for more options. I like --jsdebugger, --run-until-failure,
# --no-autorun, and --keep-open

Let's write a really simple mochitest-browser test!

• Firefox will open, and our test will start
• Our test will open a new tab
• Our test will make sure there are now 2 tabs
• Our test will close the tab it had opened

Get the test registered

• Find out where to put it. Let's put it under

  browser/base/content/test/general

  for now
• Give it a name. Let's call it

  browser_simpletest.js

• add_task(function*() {
    ok(true, "My test didn't run.");
  });
  

• Find the browser.ini
• Add browser_simpletest.js to browser.ini
• Make sure our test will run

  ./mach test browser/base/content/test/general/browser_simpletest.js

Let's write our actual test

Let's run it!

./mach test browser/base/content/test/general/browser_simpletest.js

Let's debug it if necessary

Fin