babel-plugin-jsx-property-alias

Babel plugin for making React property aliases.

The babel options for this plugin have changed for version 2. If you're using version 1 of this plugin, please see the instructions for v1 or upgrade following the instructions bellow.

Why

This plugin was created as a workaround for the issue with appium not finding testID properties in React Native ecosystem: testID information not visible on UIAutomator in Appium and [e2e-testing][Appium] Adding support for android:id.

The underlying idea is that using accessibilityLabel is a human-readable label intended to be read out to blind users. Abusing it as a view id on views that should not be read to blind users is a very bad practice.

As such, this plugin allows you to set testID properties in your code and, on a qa environment the testID properties will be duplicated into accessibilityLabel or whatever else you require.

If an accessibilityLabel property has been previously defined, it will be replaced by the testID value. This is ok if the build is specific for appium.

Despite the above, this plugin is not specific to react native. You can use it to alias any property while using jsx. See usage section for more details.

Installation

yarn add -D babel-plugin-jsx-property-alias

Usage

First set the BABEL_ENV to QA on your scripts:

{
  "scripts": {
    "appium": "BABEL_ENV=appium appium ..."
  }
}

Then change your babel configuration to include this plugin when the BABEL_ENV equals QA (or whatever you've set the BABEL_ENV to be).

Create accessibilityLabel alias from testID property

{
  "env": {
    "QA": {
      "plugins": [
        ["jsx-property-alias", {
          "properties": {
            "testID": "accessibilityLabel"
          }
        }]
      ]
    }
  }
}

Create accessibilityLabel alias from testID property and bar alias from foo property.

{
  "env": {
    "QA": {
      "plugins": [
        ["jsx-property-alias", {
          "properties": {
            "testID": "accessibilityLabel",
            "foo": "bar"
          }
        }]
      ]
    }
  }
}

React Native

As of the time of writing, if you're using React Native, there's an additional issue where neither BABEL_ENV nor NODE_ENV can be used to specify different plugins for different babel environments. You can read about this issue here.

To address this issue this plugin, from version 2, allows you to whitelist a set of environments through the includeInEnvironments option. When this option is set, the plugin will only run when the value of ALIAS_ENVIRONMENT is whitelisted.

{
  "presets": [
    "react-native"
  ],
  "plugins": [
    ["jsx-property-alias", {
      "includeInEnvironments": ["QA"],
      "properties": {
        "testID": "accessibilityLabel"
      }
    }]
  ]
}

You can now run the app like:

ALIAS_ENVIRONMENT=QA react-native start [--reset-cache]

Or if you want to bundle the JS:

ALIAS_ENVIRONMENT=QA react-native bundle [--reset-cache] # other options...

A note about caching. React Native Bundler will cache the bundle and try to avoid re-compilation unless the code changes. Make sure that you clean up your cache while running the app in different modes.

Complex project structures

Alternatively, you can abuse the projectRoots option of React Native CLI to address this. This option is suited for more complex project structures like monorepos.

Create a .babelrc file in a subfolder:

• babel-conf/.babelrc

{
  "presets": [
    "react-native"
  ],
  "plugins": [
    ["jsx-property-alias", {
      "properties": {
        "testID": "accessibilityLabel"
      }
    }]
  ]
}

Then you can launch your app as

yarn react-native start --projectRoots $PWD/babel-conf/,$PWD

Example

You can find additional examples under src/__tests__/fixtures/

In

class Foo extends React.Component {
  render() {
    return (
      <div className="bar" testID="thisIsASelectorForAppium">
        Hello Wold!
      </div>
    );
  }
}

Out

class Foo extends React.Component {
  render() {
    return (
      <div className="bar" testID="thisIsASelectorForAppium" accessibilityLabel="thisIsASelectorForAppium">
        Hello Wold!
      </div>
    );
  }
}

License

MIT