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.