Package Exports

yiewd

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (yiewd) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Yiewd

Yiewd is a Wd.js wrapper that uses V8's new generators for cleaner code! It's called yiewd because it uses the new yield syntax with wd. yield + wd = yiewd. Amazing, right? And a great way to exercise vowel pronunciation.

Yiewd is made possible with the monocle.js library.

The problem

Let's say we want to write a webdriver test:

var wd = require('wd')
  , driver = wd.remote();

driver.init(desiredCaps, function(err, sessionId) {
  if (err) return postTest(err);
  driver.get("http://mysite.com", function(err) {
    if (err) return postTest(err);
    driver.elementById("someId", function(err, el) {
      if (err) return postTest(err);
      el.click(function(err) {
        if (err) return postTest(err);
        setTimeout(function() { // pause a bit
          driver.elementById("anotherThing", function(err, el2) {
            if (err) return postTest(err);
            el2.text(function(err, text) {
              if (err) return postTest(err);
              text.should.equal("What the text should be");
              driver.quit(postTest);
            });
          });
        }, 1500); // what's this random number doing here? It goes with the pause!
      });
    });
  });
});

Yeah, that sucks. Look at that callback pyramid! Look at all those error checks!

The (generator-based) solution

Let's all be a little more sane, shall we?

wd.remote().run(function*() {
  var sessionId, el, el2, text;
  sessionId = yield this.init(desiredCaps);
  yield this.get("http://mysite.com");
  el = yield this.elementById("someId");
  yield el.click();
  yield this.sleep(1.5);
  el2 = yield this.elementById("anotherThing")
  text = yield el2.text();
  text.should.equal("What the text should be");
  yield this.quit();
});

Niiice.

How it works

Basically, you get a driver object as a result of the call to wd.remote(). You can use this driver object inside a monocle o-routine to yield to asynchronous function execution rather than using callbacks. And you'll get the result of the callback as the assignment to the yield expression!

It takes a slight change in how you think, but it's so much better than callbacks.

Integrating with test suites

It's relatively easy to break up bits of sessions between testcases and so on. Here's what a simple mocha test suite could look like:

describe('my cool feature', function() {
  var driver = null;  // driver object used across testcases

  // global setUp, tearDown
  before(function(done) {
    driver = yiewd.remote();
    driver.run(function*() {
      yield this.init(desiredCaps);
      done();
    });
  });
  after(function(done) {
    driver.run(function*() {
      yield this.quit();
      done();
    });
  });

  it('should do some thing', function(done) {
    driver.run(function*() {
      // test logic
      done();
    });
  });

  it('should do another thing', function(done) {
    driver.run(function*() {
      // test logic
      done();
    });
  });
});

Notice how you get a driver object from yiewd.remote(). You can hold onto this and later use driver.run() and pass it another generator which will take over execution for the driver. Easy!

Composing functionality

Using monocle.js, you can compose your own custom automation behaviors:

var o_O = require('monocle.js').o_O;

describe('my cool feature', function() {
  var driver = null;  // driver object used across testcases

  var flow1 = o_O(function*() {
    yield driver.get('http://mywebpage.com');
    var firstLink = yield driver.elementByCss('a');
    yield firstLink.click();
  });

  var flow2 = o_O(function*() {
    var textBox = yield driver.elementByCss('input[type=text]');
    yield textBox.sendKeys("my text");
    yield (yield driver.elementById('submit')).click();
  });

  it('should do some thing', function(done) {
    yield driver.init(desiredCaps);
    yield flow1();
    yield flow2();
    yield flow1();
    done();
  });

});

Integrating with Sauce Labs

We've got some special sauce so you can sauce while you Sauce:

yiewd.sauce(userName, accessKey).run(function*() {
  yield this.init(desiredCaps);
  yield this.get('http://saucelabs.com/guinea-pig/');
  try {
    var title = yield this.title();
    title.should.include("I am a page title");
    yield this.reportPass();
  } catch (e) {
    yield this.reportFail();
  }
});

Probably the pass/fail reporting would be handled in some kind of global tearDown method, of course.

Requirements

Node >= 0.11.3 (one with generators)
Make sure you start your test runner with the --harmony flag; this might be non-trivial but for mocha, see below.
For running tests: npm install -g mocha

Run the Tests

Make sure you have your chromedriver-enabled Selenium server running, then:

mocha -R spec -t 60000 --harmony test/

Architecture

This is a simple wrapper around Wd.js that is really easy to maintain: (a) new methods from Wd.js can be added with one word in Yiewd, (b) there's nothing really to maintain beyond the generator glue which should stabilize quickly.

Contributing

Give it a whirl and contribute bugfixes! Pull requests welcome. Biggest area of need right now is filling out our testsuite to make sure everything works correctly.