@netsells/simulate-user

@netsells/simulate-user

Library for simulating user interactions using JavaScript in the browser

Installation

yarn add @netsells/simulate-user

Usage

import SimulateUser from '@netsells/simulate-user';

const sim = new SimulateUser();

const el = await sim.find({ query: 'a', text: 'Click me' });
await el.click();

Documentation

Classes

DebugUser

Helper class for providing debug information.

SimulateUser

Simulate a user.

Functions

getDebugUser(Klass) ⇒ object

Get a debug user extending a user class.user.

get(target, prop) ⇒ any

Get the needed property.

Typedefs

SearchProperties : object

ValueSelector : SearchProperties | string | number

A generic value selector. For a textarea or input it should always be a string or number, for a select it can be a string or a SearchProperties.

DebugUser

Helper class for providing debug information.

Kind: global class

• DebugUser
  • new DebugUser(...args)
  • .build(...args) ⇒ Proxy.<object>
  • .emit(callback, ...args)
  • .on(...args)

new DebugUser(...args)

Setup the class.

Param	Type
...args	any

debugUser.build(...args) ⇒ Proxy.<object>

Generate a instance using the same class constructor and debug emitter.

Kind: instance method of DebugUser

Param	Type
...args	any

debugUser.emit(callback, ...args)

Emit and log an event.

Kind: instance method of DebugUser

Param	Type
callback	string
...args	any

debugUser.on(...args)

Listen to a debug event.

Kind: instance method of DebugUser

Param	Type
...args	any

SimulateUser

Simulate a user.

Kind: global class

• SimulateUser
  • new SimulateUser(node)
  • .visible ⇒ boolean
  • .hidden ⇒ boolean
  • .nextElementSibling ⇒ SimulateUser | null
  • .options ⇒ Array.<string>
  • .text ⇒ string
  • .directText ⇒ string
  • .parentElement ⇒ SimulateUser
  • .className ⇒ string
  • .value ⇒ string
  • .htmlFor ⇒ string
  • .tag ⇒ string
  • .build(...args) ⇒ Proxy.<SimulateUser>
  • .sleep(timeout) ⇒ Promise.<undefined>
  • .timeout(func, limit) ⇒ Promise.<*>
  • .getEventOptions(options) ⇒ object
  • .querySelectorAll(query) ⇒ Array.<SimulateUser>
  • .getElementById(id) ⇒ SimulateUser | null
  • .getElementsByName(name) ⇒ Array.<SimulateUser>
  • .closest(...args) ⇒ SimulateUser | null
  • .all(options) ⇒ SimulateUser | null
  • .first(options) ⇒ SimulateUser | null
  • .find(options, limit) ⇒ SimulateUser
  • .field(label, [findOptions]) ⇒ SimulateUser | null
  • .fieldSet(legend) ⇒ SimulateUser | null
  • .dispatchEvent(event)
  • .click(search)
  • .attach(files)
  • .check(checked)
  • .focus()
  • .blur()
  • .typeKey(key)
  • .type(text)
  • .typeValue(text)
  • .fillIn(label, value) ⇒ SimulateUser
  • .fill(value)
  • .select(value)
  • .sendChangeEvent()

new SimulateUser(node)

Create a SimulateUser class for a page element.

Param	Type
node	HTMLElement

simulateUser.visible ⇒ boolean

Check if the node is visible.

Kind: instance property of SimulateUser

simulateUser.hidden ⇒ boolean

Check if the node is hidden.

Kind: instance property of SimulateUser

simulateUser.nextElementSibling ⇒ SimulateUser | null

NextElementSibling but returns a wrapper.

Kind: instance property of SimulateUser

simulateUser.options ⇒ Array.<string>

Get all select option values.

Kind: instance property of SimulateUser

simulateUser.text ⇒ string

Get trimmed text content.

Kind: instance property of SimulateUser

simulateUser.directText ⇒ string

Get text content which is a direct child of this node.

Kind: instance property of SimulateUser

simulateUser.parentElement ⇒ SimulateUser

Get the parentElement in a wrapper.

Kind: instance property of SimulateUser

simulateUser.className ⇒ string

Proxy for className.

Kind: instance property of SimulateUser

simulateUser.value ⇒ string

Proxy for value.

Kind: instance property of SimulateUser

simulateUser.htmlFor ⇒ string

Proxy for htmlFor.

Kind: instance property of SimulateUser

simulateUser.tag ⇒ string

TagName but lower case.

Kind: instance property of SimulateUser

simulateUser.build(...args) ⇒ Proxy.<SimulateUser>

Generate a instance using the same class constructor and debug emitter.

Kind: instance method of SimulateUser

Param	Type
...args	any

simulateUser.sleep(timeout) ⇒ Promise.<undefined>

Returns a promise which resolves in a certain amount of milliseconds.

Kind: instance method of SimulateUser

Param	Type
timeout	number

simulateUser.timeout(func, limit) ⇒ Promise.<*>

Returns a promise which times out if the passed in promise doesn't resolve in time.

Kind: instance method of SimulateUser

Param	Type
func	function
limit	number

simulateUser.getEventOptions(options) ⇒ object

Get options for an event.

Kind: instance method of SimulateUser

Param	Type
options	object

simulateUser.querySelectorAll(query) ⇒ Array.<SimulateUser>

Proxy for querySelectorAll but returns an array of wrappers instead of nodes.

Kind: instance method of SimulateUser

Param	Type
query	string | Array.<string>

simulateUser.getElementById(id) ⇒ SimulateUser | null

GetElementById but returns a wrapper.

Kind: instance method of SimulateUser

Param	Type
id	string

simulateUser.getElementsByName(name) ⇒ Array.<SimulateUser>

GetElementsByName but returns an array of wrappers.

Kind: instance method of SimulateUser

Param	Type
name	string

simulateUser.closest(...args) ⇒ SimulateUser | null

Closest but returns a wrapper.

Kind: instance method of SimulateUser

Param	Type
...args	any

simulateUser.all(options) ⇒ SimulateUser | null

Search through page elements as a user would, using text.

Kind: instance method of SimulateUser

Param	Type
options	SearchProperties

simulateUser.first(options) ⇒ SimulateUser | null

Get the first element of a query to all.

Kind: instance method of SimulateUser

Param	Type
options	SearchProperties

simulateUser.find(options, limit) ⇒ SimulateUser

Get the first element of a query to all, but throws an error if it's not found. Will wait for an element to appear (e.g. If a form is updating).

Kind: instance method of SimulateUser
Throws:

• Error

Param	Type	Description
options	SearchProperties
[options.similar]	boolean	If no exact matches found, fall back to a fuzzy search.
limit	number

simulateUser.field(label, [findOptions]) ⇒ SimulateUser | null

Get a field based on its label.

Kind: instance method of SimulateUser
Throws:

• Error

Param	Type	Default
label	string
[findOptions]	object	{}

simulateUser.fieldSet(legend) ⇒ SimulateUser | null

Get a fieldset based on its legend.

Kind: instance method of SimulateUser
Throws:

• Error

Param	Type
legend	string

simulateUser.dispatchEvent(event)

Proxy for dispatchEvent.

Kind: instance method of SimulateUser

Param	Type
event	Event

simulateUser.click(search)

Click this node.

Kind: instance method of SimulateUser

Param	Type	Default
search	SearchProperties

simulateUser.attach(files)

Attach files to this input element.

Kind: instance method of SimulateUser

Param	Type
files	Array.<Files>

simulateUser.check(checked)

Check this checkbox.

Kind: instance method of SimulateUser

Param	Type	Default
checked	boolean	true

simulateUser.focus()

Focus this element.

Kind: instance method of SimulateUser

simulateUser.blur()

Blur this element.

Kind: instance method of SimulateUser

simulateUser.typeKey(key)

Type a single key on this element.

Kind: instance method of SimulateUser

Param	Type
key	string

simulateUser.type(text)

Type a string on this element.

Kind: instance method of SimulateUser

Param	Type
text	string

simulateUser.typeValue(text)

Type into a fields value. Only simulates the final key press then triggers a single change event.

Kind: instance method of SimulateUser

Param	Type
text	string | number

simulateUser.fillIn(label, value) ⇒ SimulateUser

Find a field by its label then fill it in.

Kind: instance method of SimulateUser
Returns: SimulateUser - - The field wrapper.

Param	Type
label	string
value	ValueSelector

simulateUser.fill(value)

Fill in this node as a field.

Kind: instance method of SimulateUser

Param	Type
value	ValueSelector

simulateUser.select(value)

Change a value by the option text.

Kind: instance method of SimulateUser

Param	Type
value	ValueSelector

simulateUser.sendChangeEvent()

Send a change event.

Kind: instance method of SimulateUser

getDebugUser(Klass) ⇒ object

Get a debug user extending a user class.user.

Kind: global function

Param	Type
Klass	SimulateUser

get(target, prop) ⇒ any

Get the needed property.

Kind: global function

Param	Type
target	object
prop	any

SearchProperties : object

Kind: global typedef
Properties

Name	Type	Description
text	string	Text to search on.
query	string	Optional query to filter on.
caseSensitive	boolean	Whether text is case sensitive.
exact	boolean	Whether text match should be exact (not including trimmed white space).
predicate	function	Predicate function wrappers must match.
visible	boolean	If element must be visible or not.
direct	boolean	If text should be a direct child or not.

ValueSelector : SearchProperties | string | number

A generic value selector. For a textarea or input it should always be a string or number, for a select it can be a string or a SearchProperties.

Kind: global typedef