0.4.0-alpha
GitHub Repository

API

Classes

Environment

It manages the use of environment variables by providing useful methods for checking and obtaining the variables.

Process

Provides Puppeteer initialization by creating Browser and Page instances to provide the browser context necessary for the execution of a custom function.

Functions

Process.([browserOptions]) ⇒ Promise.<object>

Creates the Browser and Page instances.

Process.(page)

Exposes the logger function to be used in the browser.

Environment

It manages the use of environment variables by providing useful methods for checking and obtaining the variables.

Kind: global class

environment.PRODUCTION

Value of the variable defined by the NodeJS processor to identify the Production execution environment.

Kind: instance property of Environment

environment.IMPRESSIONIST_VERSION

The current version of the library. It can be used, for example, for bug reporting plugins.

Kind: instance property of Environment

Environment.is(environment) ⇒ boolean

Check if a specific environment is running. i.e prod or dev.

Kind: static method of Environment Returns: boolean - Result true or false.

Example

if(Environment.is(Environment.PRODUCTION)) {
     ...
}

Environment.has(variable) ⇒ boolean

Check if a specific environment variable exists.

Kind: static method of Environment Returns: boolean - Result true or false.

Example

if(Environment.has('SENTRY_TAGS')) {
     ...
}

Environment.get(variable) ⇒ string | Array | object | null

Return a specific env var. If not exist return null.

Kind: static method of Environment

Example

for(const [name, value] of Object.entries(Environment.get('SENTRY_TAGS'))) {
     sentry.setTag(name, value);
}

Process

Provides Puppeteer initialization by creating Browser and Page instances to provide the browser context necessary for the execution of a custom function.

Kind: global class Summary: Initialize Puppeteer.

Process.execute(url, customFunction) ⇒ Promise

It provides the necessary context to run a function in the puppeteer or browser context by executing a series of steps, such as initializing a Browser instance and applying extra configurations defined by an input parameter, initializing a Page instance and applying default configurations to it so that the Impressionist library can be used in the browser context of that specific instance.

Kind: static method of Process Returns: Promise - Promise object that represents the result of the custom function.

Properties

Example (Basic Usage)

(async () => {
    const data = await Impressionist.Process.execute(url, scrape);
    console.log(JSON.stringify(data));
})(scrape);

async function scrape(browser, page) {
     ...
}

Example (Enabling Browser User Interface)

(async () => {
    const data = await Impressionist.Process.execute(url, scrape, { browserOptions: { headless: false } } );
    console.log(JSON.stringify(data));
})(scrape);

async function scrape(browser, page) {
     ...
}

Process.openConnection(url, [browserOptions]) ⇒ Promise.<object>

Open a connection to a browser instance.

Kind: static method of Process Returns: Promise.<object> - Promise object that represents an object that stores the browser, page instances.

Process.createPage(browser) ⇒ Promise.<object>

Creates a new instance of Page.

Kind: static method of Process Returns: Promise.<object> - Promise object that represents a Page instance.

Example (Create a second Page instance)

(async () => {
    const data = await Impressionist.Process.execute(url, scrape);
    console.log(JSON.stringify(data));
})(scrape);

async function scrape(browser, page) {
     const resultMainPage = await page.evaluate(...);
     
     // Need for a second page instance
     const secondPage = await Impressionist.Process.createPage(browser);

     ...

}

Process.setPageConfigurations(page, url) ⇒ Promise.<void>

Method that takes as a parameter the Page instance that is started internally within the class. The method can modify the behavior of the Page instance. Please read the documentation about the Page instance.

Kind: static method of Process Returns: Promise.<void> - Promise object that represents the method execution completion.

Properties

Example (Create a second Page instance and apply default configurations)

(async () => {
    const data = await Impressionist.Process.execute(url, scrape);
    console.log(JSON.stringify(data));
})(scrape);

async function scrape(browser, page) {
     const resultMainPage = await page.evaluate(...);
     
     // Need for a second page instance
     const secondPage = await Impressionist.Process.createPage(browser);
     
     // Apply default configurations
     await Impressionist.Process.setPageConfigurations(secondPage, 'https://...');
     
     // Using the second Page instance
     const resultSecondPage = await secondPage.evaluate(...);

     ...

}

Example (Create a second Page instance and set a different viewport)

(async () => {
    const data = await Impressionist.Process.execute(url, scrape);
    console.log(JSON.stringify(data));
})(scrape);

async function scrape(browser, page) {
     const resultMainPage = await page.evaluate(...);
     
     // Need for a second page instance
     const secondPage = await Impressionist.Process.createPage(browser);
     
     // Apply different configurations
     await Impressionist.Process.setPageConfigurations(secondPage, 'https://...', {
         viewport: {
             width: 1920,
                    height: 1080,
                    deviceScaleFactor: 1
         }
     });
     
     // Using the second Page instance
     const resultSecondPage = await secondPage.evaluate(...);

     ...

}

Process.connect(browserWSEndpoint, customFunction, [...args]) ⇒ Promise.<any>

Execute a function in a specific browser endpoint.

Kind: static method of Process Returns: Promise.<any> - Promise object that represents the result of the custom function.

Process.([browserOptions]) ⇒ Promise.<object>

Creates the Browser and Page instances.

Kind: global function Returns: Promise.<object> - Promise object that represents an object that stores the browser, page instances.

Process.(page)

Exposes the logger function to be used in the browser.

Kind: global function

Classes

MonitorManager

Log on each of the subscribed monitoring tools.

Pino

Initialize Pino and expose its functionality for login.

Sentry

Provides an interface for Sentry integration with Puppeteerist.

Functions

Sentry.()

Perform the necessary steps to configure Sentry.

MonitorManager

Log on each of the subscribed monitoring tools.

Kind: global class

MonitorManager.log(report)

Register a report.

Kind: static method of MonitorManager

MonitorManager.subscribe(logger)

Subscribe to a monitoring or logging tool.

Kind: static method of MonitorManager

MonitorManager.unsubscribe(logger)

Unsubscribe to a monitoring or logging tool.

Kind: static method of MonitorManager

MonitorManager.clear()

Delete all logers. It can be used to discard the default loggers.

Kind: static method of MonitorManager

Pino

Initialize Pino and expose its functionality for login.

Kind: global class

Pino.log(report)

Log a report.

Kind: static method of Pino

Sentry

Provides an interface for Sentry integration with Puppeteerist.

Kind: global class

Sentry.log(report)

Log a report.

Kind: static method of Sentry

Sentry.sendException(error) ⇒ Promise.<void>

Send error generated to Sentry while Puppeteer execution.

Kind: static method of Sentry Returns: Promise.<void> - Promise object that represents end of the Sentry actions.

Sentry.()

Perform the necessary steps to configure Sentry.

Kind: global function Example

Sentry.setConfigurations();

Classes

Collector

Collect items from a Collection by being iterated through a context element.

Context

It provides a data structure to control the context, which is an object with two properties. The first is document, which refers to the document object present in the browser context. If the context is not running in Browser context then document is set to null. The other property is element, which stores an element that will be used by some instance during the execution of the collectable tree.

SelectorError

Custom error to be used by the QuerySelector class in case an element or series of elements does not exist in the DOM.

CustomError

Custom error to be used by the Collectable class to identify if the error was created by the error or require methods of the same class.

CollectableError

Custom error to be used by the Collectable class to return any error caused in the execution of the Collectable tree and that does not have a Collectable default method specified.

Logger

Log useful information and register errors.

StrategyManager

Provides a common method to share across the different strategies managers.

TypeValidator

Provides a static method that checks the data type of an incoming value.

LazyLoadHandler

Loads all DOM elements that are handled by a LazyLoad.

Pagination

Handles the pagination of an HTML section.

Functions

Logger.(elements) ⇒ Array.<object>

Extract useful information from elements and give them a specific format inside a list.

Collector

Collect items from a Collection by being iterated through a context element.

Kind: global class

new Collector(contextAccessor, collection)

collector.iterationQuery

Queries to append in iterate method.

Kind: instance property of Collector

collector.call(context) ⇒ Promise.<Array>

Execute the collector.

Kind: instance method of Collector Returns: Promise.<Array> - An object that represents a promise for the collected items.

Example

        await page.evaluate(async () => {
    
            const data = ( function () {

                const css = SelectorDirectory.get('css');

                return new Collector(
                    new Collection({
                        name: css('h1').property('innerText').single()
                    })
                );
                
            } )();
        
        const context = new Context();
        console.log(await data.call(context)); // [{ name: 'Plato Plugin' }]
    });

collector.iterate(queries) ⇒ Collector

Creates a new Collector that have a custom accessor and a collection.

Kind: instance method of Collector Returns: Collector - A Collector instance.

Example

        await page.evaluate(async () => {

            const data = ( function () {

                const css = SelectorDirectory.get('css');
    
                return new ElementCollectorFactory('{#reviews > ul > li}*').iterate({
                    author: '#review-author',
                    title: '#review-title',
                    rating: '#review-rating',
                    body: '#review-body',
                    date: '#review-date'
                });
        
            } )();

            const context = new Context();
            console.log(await data.call(context)); // [{ author: 'John Doe', title: 'It is okay', rating: '4', body: 'Nice product. I would recommend the version X.', date: '01-12-2021' }, { author: 'Richard Roe', title: 'Amazing!', rating: '5', body: 'Really good product.', date: '10-12-2021' }]
        });

Context

It provides a data structure to control the context, which is an object with two properties. The first is document, which refers to the document object present in the browser context. If the context is not running in Browser context then document is set to null. The other property is element, which stores an element that will be used by some instance during the execution of the collectable tree.

Kind: global class Summary: Create an object to give context to instance executions.

context.clone() ⇒ Context

Create a new instance of the same class and assign the values of the object from which it was created. The reason for this method is that the values of the element property can be updated or modified without affecting the original context object, since the new instance is a completely independent object from the original one. Something that does not happen with a simple copy of objects.

Kind: instance method of Context Summary: Clones a context instance. Returns: Context - Object that represents the context or the element that is being passed on nested instances executions. Example (Clone an existing Context instance.)

const context = new Context();
const newContext = context.clone();

context.update(element) ⇒ Context

Update the context object by adding a new value for the element property. First, clone the existing Context object using the clone () method and then update the value of element.

Kind: instance method of Context Summary: Update the Context object. Returns: Context - Object that represents the context or the element that is being passed on nested instances executions.

Example (Update an existing Context instance.)

const context = new Context();
const newContext = context.update('new element');

context.getElement() ⇒ string | Array | Object

Gets the value of the element property. If element is equal to null then it will return the value of the document property.

Kind: instance method of Context Returns: string | Array | Object - an element that will be used by some instance during the execution of the collectable tree. Example (Getting the node to be used for nested executions)

const context = new Context();
...
const element = context.getElement();

SelectorError

Custom error to be used by the QuerySelector class in case an element or series of elements does not exist in the DOM.

Kind: global class

new SelectorError(selector)

CustomError

Custom error to be used by the Collectable class to identify if the error was created by the error or require methods of the same class.

Kind: global class

new CustomError(message)

CollectableError

Custom error to be used by the Collectable class to return any error caused in the execution of the Collectable tree and that does not have a Collectable default method specified.

Kind: global class

new CollectableError(message, history)

Logger

Log useful information and register errors.

Kind: global class

Logger.error(origin, message)

Error level.

Kind: static method of Logger

Logger.warn(origin, elements, message)

Warn level.

Kind: static method of Logger

Logger.info(origin, elements, message)

Info level.

Kind: static method of Logger

Logger.debug(origin, elements, message)

Debug level.

Kind: static method of Logger

StrategyManager

Provides a common method to share across the different strategies managers.

Kind: global class

StrategyManager.lookUp(element, strategies) ⇒ Promise.<object>

Search or look up the best strategy.

Kind: static method of StrategyManager Returns: Promise.<object> - An object that represents a promise for a specific strategy.

TypeValidator

Provides a static method that checks the data type of an incoming value.

Kind: global class

TypeValidator.check(value, [type]) ⇒ Error | void

Check the entry value if its data type of instance is the same than the type argument.

Kind: static method of TypeValidator Returns: Error | void - - Throws an error if the type does not match the value's data type.

Example (Checking if values is String)

TypeValidator.check('name');

Example (Checking if value is Number)

TypeValidator.check(5, 'number');

TypeValidator.deepCheck(value, type)

Check recursively if he entry value if its data type of instance is the same than the type argument.

Kind: static method of TypeValidator

LazyLoadHandler

Loads all DOM elements that are handled by a LazyLoad.

Kind: global class

LazyLoadHandler.execute(buttonSelector)

Executes the loading of all the elements by providing a clickable element selector, for example, a Next button.

Kind: static method of LazyLoadHandler

Pagination

Handles the pagination of an HTML section.

Kind: global class

Pagination.execute(buttonSelector, [time])

Create a generator object with the new rendered document.

Kind: static method of Pagination

Logger.(elements) ⇒ Array.<object>

Extract useful information from elements and give them a specific format inside a list.

Kind: global function Returns: Array.<object> - - List of objects that represent an element.

Classes

Collection

Execute a set of queries.

IterableAccessor

Iterates over each item in context created by a collection, returning it to be collected upon.

ProxyAccessor

Default ContextAcessor, used when there is not contextProcessor in Collector.

CollectionCollectorFactory

Shortcut to create a Collector isntances for collecting a collection for each iterable item in the context.

ElementCollectorFactory

Shortcut to create Collector that returns a NodeList of DOM elements.

OptionCollectorFactory

Shortcut to create Collector that returns a list of combinations generated by Options intances.

Option

Creates an iterable object from a series of options and at the same time, the iterable object has a function that is executed in each iterative cycle (next method call) to select a specific option value.

OptionStrategyManager

Manage the OptionStrategies.

Functions

OptionCollectorFactory.(options) ⇒ object

Execute normalization actions for each of the options. For example, adding default values in queries.

OptionCollectorFactory.(collector, options)

Add queries to the Collector instance to extract each of the options in the Collector run.

Collection

Execute a set of queries.

Kind: global class

new Collection(queries)

collection.call(context) ⇒ Promise.<object>

Execute a set of queries.

Kind: instance method of Collection Returns: Promise.<object> - An object that represents a promise for a object with the results of the queries.

Example

        await page.evaluate( async () => {
            const data = new Collection({
                name: css('h1').property('innerText').single()
            });
                
            const context = new Context();
            console.log(await data.call(context)); // { name: 'Plato Plugin' }
        });

collection.postProcessor(customProcessor) ⇒ Collection

Add a new postProcessor to the list.

Kind: instance method of Collection Returns: Collection - Returns the current Collection instance.

IterableAccessor

Iterates over each item in context created by a collection, returning it to be collected upon.

Kind: global class

new IterableAccessor(collection)

iterableAccessor.call(context) ⇒ Promise.<Generator>

Create a generator to pass the new context.

Kind: instance method of IterableAccessor Returns: Promise.<Generator> - An object that represents a promise for a generator of context objects.

Example (Receives a Collection and returns an iterable of Context objects)

        await page.evaluate( async () => {
                        
            const data = new IterableAccessor(
                new Collection({
                    reviews: () => Array.from(document.querySelectorAll('#reviews > ul > li'))
                }).postProcessor(CollectionElementProcessor)
            );

            const context = new Context();

            for await(let newContext of data.call(context)) {
                console.log(newContext); // Returns the li elements inside of a Context object.
            }
        });

ProxyAccessor

Default ContextAcessor, used when there is not contextProcessor in Collector.

Kind: global class

proxyAccessor.call(context) ⇒ Generator.<Context>

Returns a generator with the incoming context.

Kind: instance method of ProxyAccessor Returns: Generator.<Context> - Returns the incoming context as part of a generator.

Example

        await page.evaluate( async () => {
                        
            const context = new Context().update('Custom Context');

            const data = new ProxyAccessor().call(context);

            let contextContainer = [];

            for await(let newContext of data) {
                contextContainer.push(newContext);
            }

            console.log(contextContainer[0].getElement()); // 'Custom Context'
            
        });

CollectionCollectorFactory

Shortcut to create a Collector isntances for collecting a collection for each iterable item in the context.

Kind: global class

new CollectionCollectorFactory(collector, queries)

Returns: Collector - A Collector instance.

ElementCollectorFactory

Shortcut to create Collector that returns a NodeList of DOM elements.

Kind: global class

new ElementCollectorFactory(query)

Returns: Collector - A new instance of Collector.

OptionCollectorFactory

Shortcut to create Collector that returns a list of combinations generated by Options intances.

Kind: global class

new OptionCollectorFactory(options)

Returns: Collector - A Collector instance.

Option

Creates an iterable object from a series of options and at the same time, the iterable object has a function that is executed in each iterative cycle (next method call) to select a specific option value.

Kind: global class Summary: Creates an iterable object from options.

new Option(identifier, element, [strategy])

Example (Create an Option instance of a dropwdown (select element).)

const edition = new Option('edition', document.querySelector('#select_1573'));
const support = new Option('support', document.querySelector('#select_1583'));
const installation = new Option('installation', document.querySelector('#select_1593'));

Example (Create an Option instace of a group of buttons (div elements).)

// First, we need to create a function to get the options available based on the checkboxes
function getEditionAndSupportOptions(label, element) {

     return new Promise((resolve, reject) => {

             const options = element.querySelectorAll('div'); // Get all the div elements
             let result = [];
             
             for(let option of options) {
                 result.push({
                     value: option,
                     [label]: option.innerText
                 });
             }

             resolve(result);

             });
}

// We need to create the function to make the seleccion.

async function setOption(newElement) {
     newElement.click();
     return true;
}

// Now that we have out functions we can create our Option instance.

const edition = new Option('edition', document.querySelector('div.swatch-attribute.edition > div'), { getOptions: getEditionAndSupportOptions, setOptions });

option.call()

Creates an iterable object that contains the values of an HTML element and its respective selection function. The values collection and function execution is controlled by the JavaScript Iteration Protocols.

Kind: instance method of Option Example (Use the next generator method to get the values)

const edition = new Option('edition', document.querySelector('#select_1573'));

// Note: The use of next below refers to the method on Option instance.
const editionOptions = edition.next();

// Note: The use of next below refers to the iteration protocol method.
console.log(editionOptions.next()); // {value: { value: '22334', edition: 'CE' }, done: false };
console.log(editionOptions.next()); // {value: { value: '22335', edition: 'EE' }, done: false };
console.log(editionOptions.next()); // {value: { value: '22336', edition: 'ECE' }, done: false };
console.log(editionOptions.next()); // {value: undefined, done: true };

OptionStrategyManager

Manage the OptionStrategies.

Kind: global class

OptionStrategyManager.add(strategy)

Add or register a OptionStrategy sub-class.

Kind: static method of OptionStrategyManager

Example

OptionStrategyManager.add(SelectStrategy);

OptionStrategyManager.lookUp(element) ⇒ Promise.<OptionStrategy>

Search or look up the best strategy.

Kind: static method of OptionStrategyManager Returns: Promise.<OptionStrategy> - Object that represents a promise to return a sub-class of OptionStrategy.

Example (SelectStrategy matched)

        await page.evaluate(async () => {
            const selectElement = document.querySelector('#option-1');
            const strategy = await OptionStrategyManager.lookUp(selectElement);

            console.log(strategy === SelectStrategy); // true
        });

OptionCollectorFactory.(options) ⇒ object

Execute normalization actions for each of the options. For example, adding default values in queries.

Kind: global function Returns: object - The normalized options.

OptionCollectorFactory.(collector, options)

Add queries to the Collector instance to extract each of the options in the Collector run.

Kind: global function

Classes

CollectionElementProcessor

Converts collection into a generator of elements.

CollectionOptionProcessor

Processes collected values into options.

GroupStrategy

Knows how to get and set values from a group of options.

MissingStrategy

Default strategy.

SelectStrategy

Knows how to get and set values from SELECT DOM elements.

ToogleStrategy

Knows how to get and set values from an element with two states: TRUE/FALSE.

SelectorInterpreter

Creates a query chain from a custom selector.

InterpreterStrategyManager

Manage which interpretation strategy will process the custom selector.

All ⇐ Selector

Contains the specific logic to process nested structures. In case no parameter is passed to its constructor then it will return the previous result in the execution of the chain.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Css ⇐ Selector

Contains specific logic to extract elements from the DOM using a CSS selector.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Default ⇐ Selector

Returns a default value if there the expected result is not valid.

SelectorDirectory

Provide a directory to store proxy function that will be used to instantiate the Implementation sub-classes. The directory is made up of the name of each proxy function and its sub-class constructor equivalent.

Elements

Creates a collector that will return a generator of a list of elements.

Init ⇐ Selector

Perform actions during initialization.

Iterate

Iterate a Collector instance against a set of queries.

Merge ⇐ Selector

Contains the specific Selector that allows concatenating other query Selectors.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Options

Creates a collector that will return a generator of a list of option values.

Post ⇐ Selector

Perform actions after data extraction.

Pre ⇐ Selector

Perform actions before data extraction.

Property ⇐ Selector

Contains the specific Selector to obtain properties of DOM elements.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Require ⇐ Selector

Returns an error if the result is not a valid value.

Select

Interprets Select Strings.

Single ⇐ Selector

Contains the specific Selector to check if a single element is expected as it turns out, otherwise throw an error.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Xpath ⇐ Selector

Contains specific logic to extract elements from the DOM using a xpath selector.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Functions

CollectionOptionProcessor.(options) ⇒ Promise.<Generator>

It takes Option instances and calculates all possible values ​​of the combinations of those options.

CollectionElementProcessor

Converts collection into a generator of elements.

Kind: global class

CollectionElementProcessor.call(elementCollection) ⇒ Generator.<(Element|any)>

Execute the processor.

Kind: static method of CollectionElementProcessor Returns: Generator.<(Element|any)> - A generator with DOM elements.

Example (Receives a collection with a list of DOM elements an returns an array with elements)

const result = await page.evaluate(() => {
     const elements = { reviews: Array.from(document.querySelectorAll('#reviews > ul > li')) };
     const data = CollectionElementProcessor.call(elements);
     console.log(data); // [li, li]
});

CollectionOptionProcessor

Processes collected values into options.

Kind: global class

CollectionOptionProcessor.call(elementCollection) ⇒ Promise.<Generator>

Returns all possible values ​​of the options that were passed to Collection.

Kind: static method of CollectionOptionProcessor Returns: Promise.<Generator> - An object that represents a promise object for a generator containing all the possible values processed of each option.

Example (Processing a series of options)

        const result = await page.evaluate(async () => {
                
            const options = {
                edition: document.querySelector('select#option-1'),
                support: document.querySelector('select#option-2')
            };

            const values = await CollectionOptionProcessor.call(options);

            let result = [];

            for await(let value of values) {
                console.log(value); // First Iteration: [{ value: '40', support: 'val-40' }, { value: '10', edition: 'val-10' }]
            }

        });

GroupStrategy

Knows how to get and set values from a group of options.

Kind: global class

GroupStrategy.getOptions(identifier, element) ⇒ Promise.<Array>

Extract a value that will be used to identify each option.

Kind: static method of GroupStrategy Returns: Promise.<Array> - Object that represents a promise for a list of objects.

Example (Get options from a select element)

        await page.evaluate(async () => {
            const element = document.querySelectorAll('#div-1 > div');
            const result = await GroupStrategy.getOptions('edition', element);
            console.log(result); // [ { value: div, edition: 'div-val-10'}, { value: div, edition: 'div-val-20'}, { value: div, edition: 'div-val-30' }]
        });

GroupStrategy.setOption(element, value) ⇒ Promise.<Boolean>

Select a specific option.

Kind: static method of GroupStrategy Returns: Promise.<Boolean> - Object that represents a promise for the completion of a select action.

Example (Set second option to a div element)

        await page.evaluate(async () => {
            const parentElement = document.querySelector('#div-1');
            const element = document.querySelector('#div-1 > div:nth-child(2)');

            await GroupStrategy.setOption(parentElement, element);

            console.log(parentElement.getAttribute('value')); // 20
        });

GroupStrategy.match(element) ⇒ Promise.<Boolean>

Check if the particular strategy is suitable for a certain element of the DOM.

Kind: static method of GroupStrategy Returns: Promise.<Boolean> - Object that represents a promise for a TRUE or FALSE value.

Example (Match elements)

        await page.evaluate(async () => {
            const element = document.querySelectorAll('#div-1 > div');
            console.log(await GroupStrategy.match(element)); // true
        });

MissingStrategy

Default strategy.

Kind: global class

SelectStrategy

Knows how to get and set values from SELECT DOM elements.

Kind: global class

SelectStrategy.getOptions(identifier, element) ⇒ Promise.<Array>

Extract a value that will be used to identify each option.

Kind: static method of SelectStrategy Returns: Promise.<Array> - Object that represents a promise for a list of objects.

Example (Get options from a select element)

        await page.evaluate(async () => {
            const selectElement = document.querySelector('#option-1');
            console.log(await SelectStrategy.getOptions('edition', selectElement)); // [{ value: '10', edition: 'val-10' }, { value: '20', edition: 'val-20' }, { value: '30', edition: 'val-30' }]
        });

SelectStrategy.setOption(element, value) ⇒ Promise.<void>

Select a specific option.

Kind: static method of SelectStrategy Returns: Promise.<void> - Object that represents a promise for the completion of a select action.

Example (Set second option to a select element)

        await page.evaluate(async () => {
            const selectElement = document.querySelector('#option-1');
            await SelectStrategy.setOption(selectElement, '20');
            console.log(selectElement.value); // '20'
        });

SelectStrategy.match(element) ⇒ Promise.<(Boolean|Error)>

Check if the particular strategy is suitable for a certain element of the DOM.

Kind: static method of SelectStrategy Returns: Promise.<(Boolean|Error)> - Object that represents a promise for a TRUE or FALSE value.

Example (Match a SELECT element)

        await page.evaluate(async () => {
            const selectElement = document.querySelector('#option-1');
            console.log(await SelectStrategy.match(selectElement)); // true
        });

ToogleStrategy

Knows how to get and set values from an element with two states: TRUE/FALSE.

Kind: global class

ToogleStrategy.getOptions(identifier, element) ⇒ Promise.<Array>

Extract a value that will be used to identify each option.

Kind: static method of ToogleStrategy Returns: Promise.<Array> - Object that represents a promise for a list of objects.

Example (Get options from a checkbox element)

        await page.evaluate(async () => {
            const selectElement = document.querySelector('#toogle');
            console.log(await ToogleStrategy.getOptions('installation', selectElement));
            // [{ value: { click: {}, selection: true }, installation: true }, { value: { click: {}, selection: false }, installation: false }]
        });

ToogleStrategy.setOption(element, value) ⇒ Promise.<void>

Select a specific option.

Kind: static method of ToogleStrategy Returns: Promise.<void> - Object that represents a promise for the completion of a select action.

Example (Select an input element)

        await page.evaluate(async () => {
            const inputElement = document.querySelector('#toogle > input');
            await ToogleStrategy.setOption(inputElement, { click: inputElement, selection: true });
            console.log(inputElement.checked); // true

ToogleStrategy.match(element) ⇒ Promise.<(Boolean|Error)>

Check if the particular strategy is suitable for a certain element of the DOM.

Kind: static method of ToogleStrategy Returns: Promise.<(Boolean|Error)> - Object that represents a promise for a TRUE or FALSE value.

Example (Match an element)

        await page.evaluate(async () => {
            const selectElement = document.querySelector('#toogle');
            console.log(await ToogleStrategy.match(selectElement)); // true
        });

SelectorInterpreter

Creates a query chain from a custom selector.

Kind: global class

new SelectorInterpreter(selector)

Returns: Query - A query instance.

Example

    SelectorDirectory.register(SelectorInterpreter);
    await page.evaluate(async () => { 
    
        const data = ( function () {

            const select = SelectorDirectory.get('selectorinterpreter');

            return new Collection({
                name: select('h1')
            });
            
        } )();
        
        const context = new Context();
        console.log(await data.call(context)); // Plato Plugin
    });

InterpreterStrategyManager

Manage which interpretation strategy will process the custom selector.

Kind: global class

InterpreterStrategyManager.add(strategy)

Add a new strategy.

Kind: static method of InterpreterStrategyManager

Example

        await page.evaluate(() => {
            InterpreterStrategyManager.add(InterpreterElementStrategy);
            InterpreterStrategyManager.add(InterpreterInnerTextStrategy);
            InterpreterStrategyManager.add(InterpreterPropertyStrategy);
        });

InterpreterStrategyManager.lookUp(selector) ⇒ object

Search among the available strategies which of them is the most suitable to process a specific selector.

Kind: static method of InterpreterStrategyManager Returns: object - A strategy that can process the custom selector.

Example ({h1} gets InterpreterElementStrategy)

        await page.evaluate(async () => { 
            const interpreter = InterpreterStrategyManager.lookUp('{h1}');
            console.log(interpreter === InterpreterElementStrategy ? true : false); // true
        });

All ⇐ Selector

Contains the specific logic to process nested structures. In case no parameter is passed to its constructor then it will return the previous result in the execution of the chain.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Kind: global class Summary: Process nested structures. Extends: Selector

all.alternatives

Queue of alternative definitions.

Kind: instance property of All

all.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of All Overrides: validateParameters

all.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of All Overrides: execute

all.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of All Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

all.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of All Returns: this - The instance of a Selector sub-class.

all.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of All

all.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of All Returns: this - Instance of Selector sub-class.

all.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of All Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

Css ⇐ Selector

Contains specific logic to extract elements from the DOM using a CSS selector.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Kind: global class Summary: Extracts Dom Elements. Extends: Selector

css.alternatives

Queue of alternative definitions.

Kind: instance property of Css

css.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of Css Overrides: validateParameters

css.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of Css Overrides: execute

css.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of Css Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

css.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of Css Returns: this - The instance of a Selector sub-class.

css.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of Css

css.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of Css Returns: this - Instance of Selector sub-class.

css.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of Css Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

Default ⇐ Selector

Returns a default value if there the expected result is not valid.

Kind: global class Extends: Selector

default.alternatives

Queue of alternative definitions.

Kind: instance property of Default

default.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of Default

default.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of Default Overrides: execute

default.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of Default Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

default.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of Default Returns: this - The instance of a Selector sub-class.

default.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of Default

default.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of Default Returns: this - Instance of Selector sub-class.

default.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of Default Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

SelectorDirectory

Provide a directory to store proxy function that will be used to instantiate the Implementation sub-classes. The directory is made up of the name of each proxy function and its sub-class constructor equivalent.

Kind: global class Summary: Keep a record of Selector subclasses.

SelectorDirectory.register(selector)

Saves a record of the subclass within the registry as a function.

Kind: static method of SelectorDirectory

Example (Use in Selector class)

SelectorDirectory.register(this); // 'this' referring to the class constructor that is extending Implementation.

SelectorDirectory.get(name) ⇒ function

Returns the proxy function that was previously registered within the registry object.

Kind: static method of SelectorDirectory Returns: function - Proxy function that will create the instance of the sub-class.

Example (Use in Selector class)

// Create the intance of the functionality
const queryImplementation = SelectorDirectory.get(prop);
const queryInstance = new queryImplementation(definition, this.query);

SelectorDirectory.iterate()

Creates an iterable object of all registries inside the registry object.

Kind: static method of SelectorDirectory

Elements

Creates a collector that will return a generator of a list of elements.

Kind: global class

Init ⇐ Selector

Perform actions during initialization.

Kind: global class Extends: Selector

init.alternatives

Queue of alternative definitions.

Kind: instance property of Init

init.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of Init

init.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of Init Overrides: execute

init.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of Init Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

init.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of Init Returns: this - The instance of a Selector sub-class.

init.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of Init

init.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of Init Returns: this - Instance of Selector sub-class.

init.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of Init Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

Init.register()

Modifies the record to be made in the SelectorDirectory class.

Kind: static method of Init

Iterate

Iterate a Collector instance against a set of queries.

Kind: global class

Merge ⇐ Selector

Contains the specific Selector that allows concatenating other query Selectors.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Kind: global class Summary: Concatenates query Selectors Extends: Selector

merge.alternatives

Queue of alternative definitions.

Kind: instance property of Merge

merge.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of Merge Overrides: validateParameters

merge.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of Merge Overrides: execute

merge.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of Merge Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

merge.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of Merge Returns: this - The instance of a Selector sub-class.

merge.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of Merge

merge.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of Merge Returns: this - Instance of Selector sub-class.

merge.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of Merge Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

Options

Creates a collector that will return a generator of a list of option values.

Kind: global class

Post ⇐ Selector

Perform actions after data extraction.

Kind: global class Extends: Selector

post.alternatives

Queue of alternative definitions.

Kind: instance property of Post

post.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of Post Overrides: validateParameters

post.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of Post Overrides: execute

post.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of Post Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

post.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of Post Returns: this - The instance of a Selector sub-class.

post.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of Post

post.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of Post Returns: this - Instance of Selector sub-class.

post.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of Post Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

Pre ⇐ Selector

Perform actions before data extraction.

Kind: global class Extends: Selector

pre.alternatives

Queue of alternative definitions.

Kind: instance property of Pre

pre.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of Pre Overrides: validateParameters

pre.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of Pre Overrides: execute

pre.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of Pre Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

pre.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of Pre Returns: this - The instance of a Selector sub-class.

pre.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of Pre

pre.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of Pre Returns: this - Instance of Selector sub-class.

pre.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of Pre Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

Property ⇐ Selector

Contains the specific Selector to obtain properties of DOM elements.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Kind: global class Summary: Obtain properties. Extends: Selector

property.alternatives

Queue of alternative definitions.

Kind: instance property of Property

property.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of Property Overrides: validateParameters

property.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of Property Overrides: execute

property.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of Property Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

property.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of Property Returns: this - The instance of a Selector sub-class.

property.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of Property

property.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of Property Returns: this - Instance of Selector sub-class.

property.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of Property Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

Require ⇐ Selector

Returns an error if the result is not a valid value.

Kind: global class Extends: Selector

require.alternatives

Queue of alternative definitions.

Kind: instance property of Require

require.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of Require

require.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of Require Overrides: execute

require.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of Require Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

require.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of Require Returns: this - The instance of a Selector sub-class.

require.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of Require

require.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of Require Returns: this - Instance of Selector sub-class.

require.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of Require Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

Select

Interprets Select Strings.

Kind: global class

Single ⇐ Selector

Contains the specific Selector to check if a single element is expected as it turns out, otherwise throw an error.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Kind: global class Summary: Check for a single result of the previous Selector. Extends: Selector

single.alternatives

Queue of alternative definitions.

Kind: instance property of Single

single.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of Single

single.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of Single Overrides: execute

single.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of Single Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

single.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of Single Returns: this - The instance of a Selector sub-class.

single.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of Single

single.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of Single Returns: this - Instance of Selector sub-class.

single.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of Single Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

Xpath ⇐ Selector

Contains specific logic to extract elements from the DOM using a xpath selector.

The class itself is not open to developer use, but rather is used by a proxy function to build the instance. See the example for more information.

Kind: global class Summary: Extracts Dom Elements. Extends: Selector

xpath.alternatives

Queue of alternative definitions.

Kind: instance property of Xpath

xpath.validateParameters()

Validate the instance initialization parameters.

Kind: instance method of Xpath Overrides: validateParameters

xpath.execute(context)

Method that contains all the specific Selector of the instance.

Kind: instance method of Xpath Overrides: execute

xpath.call(context) ⇒ Promise.<(string|Array.<*>|Object)>

Main method. Start the execution processes of the chained instances.

Kind: instance method of Xpath Returns: Promise.<(string|Array.<*>|Object)> - Promise object that represents the result of the chain execution.

xpath.setGetElement(context) ⇒ this

Set a new context.

Kind: instance method of Xpath Returns: this - The instance of a Selector sub-class.

xpath.getElement(context) ⇒ Any

Get the element from the context.

Kind: instance method of Xpath

xpath.alt(definition) ⇒ this

Allows the agregation of new alternatives.

Kind: instance method of Xpath Returns: this - Instance of Selector sub-class.

xpath.executeAlternatives(context) ⇒ Promise.<(object|string|Array)>

Execute the next alternative in the FIFO queue.

Kind: instance method of Xpath Returns: Promise.<(object|string|Array)> - Promise object that represents the result of the chain execution.

CollectionOptionProcessor.(options) ⇒ Promise.<Generator>

It takes Option instances and calculates all possible values ​​of the combinations of those options.

Kind: global function Returns: Promise.<Generator> - An object that represents a promise object for a generator containing all the possible values from a set of options.

PreviousAdvanced Selector

Last updated