AppFolio-IM
react-gears-cypress
What is this?
This is a collection of helpers for testing
react-gears browser UIs with
Cypress. It provides "finder" functions for finding react-gears components
in the DOM, Cypress commands for interacting with compomnents, and some fuzzy
text-matching functions to promote more reliable tests.
NOTE: due to historical precedent and the limitations of GitHub packages, this package is confusingly published to two different NPM scope names depending on the repository.
- Via npmjs.com, it is
@appfolio/react-gears-cypress - Via
npm.pkg.github.com, it is@appfolio-im/react-gears-cypress
The package contents are identical for a given version; the only difference is the distribution
mechanism.
Clients should choose a distribution repository and use the suitable corresponding scope name.
In the long run we hope to move this repository back to the @appfolio org and unify the scopes.
How do I use it?
Install the commands at startup by adding a few lines to cypress/support/commands.js:
import { commands as gears } from 'react-gears-cypress'
// Adds all commands: clear, fill, gears, select. Pass string[] to
// install just some of the commands.
gears.add();Then, in each test where you want to interact with react-gears components:
import { BlockPanel, Datapair, Input, Select } from 'react-gears-cypress';
cy.component(BlockPanel, 'Personal Information').within(() => {
cy.component(Datapair, 'First Name').contains('Alice')
cy.component(Input, 'Last Name').clear().type('Liddel')
cy.component(Select, 'Favorite Color').select('red')
})Inputs and other components are always identified by their label/title. The
intended usage is with the form-labelling component FormLabelGroup, which provides a <label> element for basically any nested component(s).
import { FormLabelGroup, Input } from '@appfolio/react-gears';
...
const TestableComponent = () => (
<FormLabelGroup label="foo"><Input/></FormLabelGroup>
)To deal with labels, values and other text whose whitespace varies, you
can use the match helpers which return a RegExp that can be passed
instead of a string for more precise or relaxed matching.
import {Datapair, match} from 'react-gears-cypress
// Matches "Name" or "Name *" but not "First Name"
cy.component(Datapair, match.exact('Name'))
// Matches "foo bar", "foo badger bar", "foo badger badger mushroom bar", etc
cy.component(Datapair, match.fuzzyFirstLast('foo', 'bar'))
// Matches "foo\nbar baz", "foo bar\nbaz", etc
cy.component(Datapair, match.fuzzyMultiline('foo bar baz'))Contributing
Building the repo
npm run buildType-checking the repo
npm run type-checkAnd to run in --watch mode:
npm run type-check:watchReleasing a new version
To release a new version:
1) Merge your work to master.
2) Check package.json for the previously released version X.Y.Z.
3) Run git log vX.Y.Z..HEAD to review new work from yourself and others. Decide on a new version number according to semver guidelines; for the sake of this example, let's say
you decide the new version will be X.Y.W.
- if you want a prerelease version, the preferred format is
X.Y.Z-rc.0(thenrc.1, etc)
4) Run npm version X.Y.W to bump to the new version you decided on above.
- You can also use
npm version <patch|minor|major>if you just want to increment one of those components.
5) Run npm run build to produce distributables with the new version number.
6) npm publish to share your distributables with the world.
- if publishing a prerelease version you must add
--tags=betato thenpm publishcommand! - otherwise, people will accidentally upgrade to your prerelease and you will be forced to support them
7) git push and git push --tags to ensure that the npm version bump is preserved
for posterity.