hermione-codemod

This repository contains a collection of codemod scripts to be used with JSCodeshift that helps to update Hermione APIs.

Setup & Run

npm install hermione-codemod --save-dev
npx jscodeshift -t <transform> <path> [...options]

transform - name of transform script, see available transforms below;
path - files or directories that should be transformed (can use glob);
options - contains options that passed to the runner of jscodeshift and to the transform script.

For example you can use the -d option for a dry-run and -p to print the output for comparison. The remaining jscodeshift options can be found here.

Included Transforms

browser-chaining-to-async-await

Transforms calls of browser commands from chaining to async-await style. Used in order to update hermione with wdio@7+ inside in which chaining of browser commands does not work anymore and tests should be rewritten to async-await. Moreover in wdio@7 result of calling browser commands does not return to value property anymore, to fix this use remove-browser-prop script.

npx jscodeshift -t hermione-codemod/transforms/browser-chaining-to-async-await.js <path> [...options]

For example (input):

it('test', function() {
  return this.browser
    .foo()
    .bar()
    .then((res) => this.browser.baz(res))
    .qux();
});

will be transformed to (output):

it('test', async function() {
  await this.browser.foo();
  const res = await this.browser.bar();
  await this.browser.baz(res);
  await this.browser.qux();
});

More examples can be found in transforms/__testfixtures__ directory.

Options

--browser-name - ability to set used name of browser instance variable in your tests. Transform script will find usage of passed browser names with chaining calls and transform them to await nodes. Default value is browser.

Example:

npx jscodeshift -t <transform> <path> --browser-name='bro1,bro2'

Input:

const fn1 = () => bro1.foo().bar();
const fn2 = () => this.bro2.baz().qux();

Output:

const fn1 = async () => {
  await bro1.foo();
  return bro1.bar();
};
const fn2 = async () => {
  await this.bro2.baz();
  return this.bro2.qux();
};

--not-await - ability to set names of called nodes that should not be awaited. For example if you do not await assert calls called inside then callback. Default value is ['assert', 'should', 'expect'].

Example:

npx jscodeshift -t <transform> <path> --not-await='assert,expect'

Input:

(function() {
  return browser.foo()
    .then(() => assert.equal(1, 1))
    .then(() => expect(2).to.equal(2));
})();

Output:

(async function() {
  await browser.foo();
  assert.equal(1, 1);
  return expect(2).to.equal(2);
})();

--break-chaining-on - ability to break chaining on nodes that matched to the passed identifiers. For example if you are using chai-as-promised that can be called on browser commands. Default value is ['assert', 'should', 'expect'].

Example:

npx jscodeshift -t <transform> <path> --break-chaining-on='should'

Input:

(function() {
  return browser.foo()
    .should.eventually.equal('foo')
    .bar();
})();

Output:

(async function() {
  await browser.foo();
  static Error("hermione-codemod_1: fix code below manually");
  should.eventually.equal('foo');
  static Error("hermione-codemod_1: fix code above manually");
  await browser.bar();
})();

After that you need to correct the test manually and in the end it might look like this:

(async function() {
  const res = await browser.foo();
  res.should.equal('foo');
  await browser.bar();
})();

Areas of improvement

Can't resolve problem with duplication of identifier declaration. Reproduced when parameters of resolve callback inside then have the same name. Currently it should be fixed manually. To simplify the search for such cases, you just need to run transform script again on the same path. Example: Input:
```
const fn = () => browser.foo()
  .then((a) => browser.bar(a))
  .then((a) => browser.baz(a));
```
Output:
```
const fn = async () => {
  const a = await browser.foo();
  const a = await browser.bar(a); // Identifier 'a' has already been declared
  return browser.baz(a);
};
```

Can't correctly handle the case with call function instead declarate resolve callback in then expression. Currently it should be fixed manually. Example: Input:

const fn = () => browser.foo().then(bar.bind(browser));

Output:

const fn = async () => {
  await browser.foo();
  return bar.bind(browser); // problem: bar function will not be called
};