Backwards compatibility break v0.9.8 -> master: selectors passed into custom commands

When a custom command (non-page command) is used from a page object using a @-named element reference, the v0.9.8 behavior will pass in the selector string when the new (current master) behavior passes in the element object.

// custom-commands/customCommand.js
exports.command = function (selector) {
  this.perform(function () {
    console.log('Selector:', selector); // see outputs below...
  });
};

// page-objects/myPageObject.js
module.exports = {
    elements: {
        simple: '.simple'
    },
    commands: []
};

// tests/test.js
module.exports = {
  test: function (browser) {
    browser.page.myPageObject().customCommand('@simple');
  },

  'after': function (browser) {
    browser.end();
  }
}

Current release (v0.9.8) output:

Selector: '.simple'

Current master output:

Selector: { name: 'simple',
  selector: '.simple',
  locateStrategy: 'css selector',
  parent:   { ...
}

If you’re just passing this value along to native commands, its fine. But if you’re doing more, for example expecting this to be a string for some other usage, then you’re going to have problems.

We had a custom command which passed this value along to an execute() which produced an Error while running execute command: Converting circular structure to JSON error because it was no longer passing a simple string, instead passing the entire element object which was causing some havoc.

While a compatibility break, this behavior is a necessary evil to allow the element’s own locateStrategy to be passed along with the selector without affecting the global locateStrategy which is part of the encapsulation capabilities of the feature.

Workaround:

// custom-commands/customCommand.js
exports.command = function (selector) {
  // for old behavior:
  selector = typeof selector === 'object' ? selector.selector : selector;
  // ... and maybe call useCss() or useXpath() if going between those strategies based on selector
  // ...
};

[beatfactor]

@qooban could you open a separate issue please regarding this? Make sure to post the verbose log as well, thanks.

[aberonni]

With the latest v1.0.14 this original error is not encountered anymore:

We had a custom command which passed this value along to an execute() which produced an Error while running execute command: Converting circular structure to JSON error

Now the behaviour has been changed with this new release, and I have documented this breaking change here: https://github.com/nightwatchjs/nightwatch/wiki/Migrating-to-Nightwatch-1.0#custom-commands

I think we can now close this issue.