Form Mutator

A utility to fill out web form and mutate field data programmatically.

Browser Download

You can download compressed copy for browser usage.

Node.js Installation

$ npm install --save form-mutator

API Reference

Provide utility to fill out web form and mutate field data programmatically.

Example (Browser usage)

<script type="text/javascript" src="form-mutator.min.js"></script>
<script>
  formMutator.fillOut({
    '[name="fullName"]': 'Your Name',
    '[name="address"]': '1 Awesome Way',
    '[name="city"]': 'Lalaland',
    '[type="submit"]': true,
  });
</script>

Example (Node.js usage)

const formMutator = require('form-mutator');

formMutator.fillOut({
  '[name="fullName"]': 'Your Name',
  '[name="address"]': '1 Awesome Way',
  '[name="city"]': 'Lalaland',
  '[type="submit"]': true,
});

• form-mutator
  • .click ⇒ boolean
  • .deselectByText ⇒ boolean
  • .fillOut ⇒ boolean
  • .selectByText ⇒ boolean
  • .setValue ⇒ boolean
  • .toggleCheckbox ⇒ boolean
  • .typeValue ⇒ boolean

form-mutator.click ⇒ boolean

Click on given element.

Kind: static property of form-mutator
Returns: boolean - Truthy if click triggered, otherwise falsy.

Param	Type	Description
element	Object	The element to click.

Example

const el = document.querySelector('a[href="/"]');
const response = formMutator.click(el);

form-mutator.deselectByText ⇒ boolean

Deselect given values from dropdown list.

Kind: static property of form-mutator
Returns: boolean - Truthy if deselect triggered, otherwise falsy.

Param	Type	Description
element	Object	The element to deselect from.
values	Array.<string>	The values to deselect.

Example

const el = document.querySelector('[name="month"]');
const response = formMutator.deselectByText(el, ['January']);

form-mutator.fillOut ⇒ boolean

Fill out all form field matched given selector => value key-pair. It will skip unknown field type and missing field.

Kind: static property of form-mutator
Returns: boolean - Truthy if the values are set, otherwise false.

Param	Type	Description
data	Object	The selector => value data map.
data.selector	string	The selector to find desired element.
data.value	mixed	The value to be set.

Example

const response = formMutator.fillOut({
  '[name="fullName"]': 'Your Name',
  '[name="address"]': '1 Awesome Way',
  '[name="city"]': 'Lalaland',
  '[type="submit"]': true,
});

form-mutator.selectByText ⇒ boolean

Select given values from dropdown list.

Kind: static property of form-mutator
Returns: boolean - Truthy if select triggered, otherwise falsy.

Param	Type	Description
element	Object	The element to select from.
values	Array.<string>	The values to select.

Example

const el = document.querySelector('[name="month"]');
const response = formMutator.selectByText(el, ['January']);

form-mutator.setValue ⇒ boolean

Set given value to input field that match given selector.

Kind: static property of form-mutator
Returns: boolean - Truthy if the value is set, or the field is unknown type or the field can not be found, otherwise false.

Param	Type	Description
selector	string	The selector to find desired element.
value	mixed	The value to be set.

Example

const response = formMutator.setValue('[type="text"]', 'value');

form-mutator.toggleCheckbox ⇒ boolean

Toggle the checkbox or radio button field.

Kind: static property of form-mutator
Returns: boolean - Truthy if toggle triggered, otherwise falsy.

Param	Type	Description
element	Object	The element to toggle from.
value	boolean	Check if true, otherwise uncheck.

Example

const el = document.querySelector('[type="checkbox"]');
const response1 = formMutator.toggleCheckbox(el, true);  // checked
const response2 = formMutator.toggleCheckbox(el, false); // unchecked

form-mutator.typeValue ⇒ boolean

Type given value to password or text field.

Kind: static property of form-mutator
Returns: boolean - Truthy if type in triggered, otherwise falsy.

Param	Type	Description
element	Object	The element to type on.
value	mixed	The value to be typed in.

Example

const el = document.querySelector('[type="text"]');
const response = formMutator.typeValue(el, 'value');

Development Dependencies

You will need to install Node.js as a local development dependency. The npm package manager comes bundled with all recent releases of Node.js.

npm install will attempt to resolve any npm module dependencies that have been declared in the project’s package.json file, installing them into the node_modules folder.

$ npm install

Run Linter

To make sure we followed code style best practice, run:

$ npm run lint

Run Unit Tests

To make sure we did not break anything, let's run:

$ npm test

Contributing

If you would like to contribute code to Form Mutator repository you can do so through GitHub by forking the repository and sending a pull request.

If you do not agree to Contribution Agreement, do not contribute any code to Form Mutator repository.

When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible. Please also include appropriate test cases.

That's it! Thank you for your contribution!

License

Copyright (c) 2018 - 2020 Richard Huang.

This utility is free software, licensed under: Mozilla Public License (MPL-2.0).

Documentation and other similar content are provided under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.