I
I
Impressionist
latest (0.5.1-beta)
Search
K
Links

API

Classes

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.

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.
Param
Type
Description
environment
string
Identifier of the ENV environment variable. For example, prod, dev, etc.
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.
Param
Type
Description
variable
string
The variable to check.
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
Param
Type
Description
variable
string
The variable to extract.
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.browserController

Provides methods and features to interact with the browser. By default, PuppeteerController.
Kind: instance property of Process

Process.execute(url, customFunction, options) ⇒ 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.
Param
Type
Description
url
string
Target URL for scraping process.
customFunction
function
Custom function to be executed in the Puppeteer context. Like customFunction(browser, page, ...args) { ... }.
options
Object
Options to configure the browser and page. Please check the browser configuration in https://pptr.dev/api/puppeteer.puppeteerlaunchoptions Please check the page navigation options in https://pptr.dev/api/puppeteer.page.goto.
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 () => {
return await Impressionist.Process.execute(
url,
function scrape() { ... },
{
browserOptions: { headless: false }
}
);
})();
Example (Set a specific page navigation timeout)
(async () => {
return await Impressionist.Process.execute(
url,
function scrape() { ... },
{
pageOptions: { timeout: 120000 },
},
);
})();

Process.initialize(url, [browserOptions]) ⇒ Promise.<symbol>

Perform actions to initialize a connection to a page using the browser controller.
Kind: static method of Process Returns: Promise.<symbol> - Promise which resolves to a connection identifier.
Param
Type
Default
Description
url
string
URL or browser Endpoint.
[browserOptions]
object
{}
Options to configure the browser controller.

Process.configureConnection(connectionIdentifier)

Configure a page connection.
Kind: static method of Process
Param
Type
Description
connectionIdentifier
symbol
Unique identifier for a page connection.

Process.enableImpressionistFeatures(connectionIdentifier)

Enable all the Impressionist features to be used in the browser context.
Kind: static method of Process
Param
Type
Description
connectionIdentifier
symbol
Unique identifier for a page connection.

Process.executeFunction(connectionIdentifier, customFunction) ⇒ Promise.<any>

Execute the function in the browser context provided by the browser controller.
Kind: static method of Process Returns: Promise.<any> - Promise which resolves to the result of the execution of the function.
Param
Type
Description
connectionIdentifier
symbol
Unique identifier for a page connection.
customFunction
function
Custom function to be executed in the Puppeteer context. Like customFunction(browser, page, ...args) { ... }.

Process.handleError(error, connectionIdentifier) ⇒ Promise.<any>

Handle errors.
Kind: static method of Process Returns: Promise.<any> - Promise which resolves to any result of error handling.
Param
Type
Description
error
Error
Error object.
connectionIdentifier
symbol
Unique identifier for a page connection.

Process.close(connectionIdentifier) ⇒ Promise.<any>

Close connections.
Kind: static method of Process Returns: Promise.<any> - Promise which resolves to any result of closing connections.
Param
Type
Description
connectionIdentifier
symbol
Unique identifier for a page connection.

Process.exposeLogger(connectionIdentifier)

Exposes the logger function to be used in the browser context.
Kind: static method of Process
Param
Type
Description
connectionIdentifier
symbol
Unique identifier for a page connection.

Process.enableCollector(connectionIdentifier)

Load the library classes in the browser environment.
Kind: static method of Process
Param
Type
Description
connectionIdentifier
symbol
Unique identifier for a page connection.

Process.registerSelectors(connectionIdentifier)

Make the registration of Selectable sub-classes using their static method register.
Kind: static method of Process
Param
Type
Description
connectionIdentifier
symbol
Unique identifier for a page connection.

Process.registerStrategies(connectionIdentifier)

Register strategies.
Kind: static method of Process
Param
Type
Description
connectionIdentifier
symbol
Unique identifier for a page connection.

Process.addProxyFunctions(connectionIdentifier)

Add functions to be used in Browser Context.
Kind: static method of Process
Param
Type
Description
connectionIdentifier
symbol
Unique identifier for a page connection.

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.
Param
Type
Default
Description
browserWSEndpoint
string
customFunction
function
Custom function to be executed in the Puppeteer context. Like customFunction(browser, page, ...args) { ... }.
[...args]
Array.<any>
[]
Any parameter necessary for the custom function.

Process.setBrowserController(browserController)

Set a browser controller which Impressionist use to interact with the browser context.
Kind: static method of Process
Param
Type
Description
browserController
object
Browser controller.

Process.loadPlugin(plugin)

Load a plugin.
Kind: static method of Process
Param
Type
Description
plugin
object
A class to extends or modify the Impressionist behavior.

Classes

Puppeteer
Controls access to puppeteer methods and features.
Provides shorcut methods to Puppeteer configurations for initialize
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.()
Add the necessary tags for Sentry. Some come from environment variables and others are defined by the library locally.

Puppeteer

Controls access to puppeteer methods and features.
Kind: global class

Puppeteer.launch([options]) ⇒ Promise.<object>

Enables a connection to control the browser.
Kind: static method of Puppeteer Returns: Promise.<object> - Promise which resolves to browser instance.
Param
Type
Default
Description
[options]
object
{}
Please read the documentation about the Launch Options.

Puppeteer.newPage(browser) ⇒ Promise.<object>

Create a new Page object.
Kind: static method of Puppeteer Returns: Promise.<object> - Promise which resolves to a new Page object. The Page is created in a default browser context.
Param
Type
Description
browser
object
Browser instance.

Puppeteer.close(...controllers)

Close any instance of Page or Browser.
Kind: static method of Puppeteer
Param
Type
Description
...controllers
any
Page or Browser instances.

Puppeteer.goto(page, url)

Navigate to a specific URL.
Kind: static method of Puppeteer
Param
Type
Description
page
object
Page instance.
url
string
URL.

Puppeteer.evaluate(page, pageFunction, ...args) ⇒ Promise.<any>

Execute a function in the browser context.
Kind: static method of Puppeteer Returns: Promise.<any> - Promise which resolves to a result of the function executed in the browser context.
Param
Type
Description
page
object
Page instance.
pageFunction
function
A function to be executed in the browser context.
...args
any
Function arguments.

Puppeteer.exposeFunction(page, name, puppeteerFunction)

Expose a NodeJS function to be called from the browser context.
Kind: static method of Puppeteer
Param
Type
Description
page
object
Page Instance.
name
string
Function name to be called from the browser context.
puppeteerFunction
function
Function that is going to be executed in the NodeJS context.

Puppeteer.addScriptTag(page, options)

Add a new script tag in the HTML layout.
Kind: static method of Puppeteer
Param
Type
Description
page
object
Page instance.
options
object
Options for load content in the script tag. Please check the documentation.

Puppeteer.addEventListener(page, method, event, handler)

Add an event listener to page.
Kind: static method of Puppeteer
Param
Type
Description
page
object
Page instance.
method
string
EventEmitter method.
event
string | symbol
The event to add the handler to.
handler
function
The event listener that will be added.

PuppeteerController

Provides shorcut methods to Puppeteer configurations for initialize
Kind: global class

puppeteerController.browser

Browser instance.
Kind: instance property of PuppeteerController

puppeteerController.pages

Page instances.
Kind: instance property of PuppeteerController

PuppeteerController.initialize(url, [options]) ⇒ Promise.<symbol>

Open a connection to an URL using a page instance.
Kind: static method of PuppeteerController Returns: Promise.<symbol> - Promise which resolves to a unique identifier represented by a Symbol.
Param
Type
Description
url
string
URL.
[options]
object
Please read the documentation about the Launch Options.

PuppeteerController.close([identifier])

Close connections.
Kind: static method of PuppeteerController
Param
Type
Description
[identifier]
symbol
Unique identifier for a page connection.

PuppeteerController.evaluate(identifier, pageFunction, ...args) ⇒ Promise.<any>

Evaluate a function in a specific page.
Kind: static method of PuppeteerController Returns: Promise.<any> - Promise which resolves to the result of the pageFunction.
Param
Type
Description
identifier
symbol
Unique identifier for a page connection.
pageFunction
function
A function to be evaluated in the browser context.
...args
any
Arguments for being passed to the pageFunction.

PuppeteerController.execute(identifier, puppeteerFunction) ⇒ Promise.<any>

Execute a function which provides browser and page as parameters.
Kind: static method of PuppeteerController Returns: Promise.<any> - Promise which resolves to the result of the puppeteerFunction.
Param
Type
Description
identifier
symbol
Unique identifier for a page connection.
puppeteerFunction
function
Custom function.

PuppeteerController.inject(identifier, functionality)

Inject a function in the HTML layout.
Kind: static method of PuppeteerController
Param
Type
Description
identifier
symbol
Unique identifier for a page connection.
functionality
function
Function to be load as a script tag in the page.

PuppeteerController.expose(identifier, functionality, [name])

Expose a NodeJS function to be used from the browser context.
Kind: static method of PuppeteerController
Param
Type
Default
Description
identifier
symbol
Unique identifier for a page connection.
functionality
function
Function to be exposed.
[name]
string
"functionality.name"
Function name to be used in the browserContext.

PuppeteerController.enableProxy(identifier, proxy)

Setting proxies per page basis.
Kind: static method of PuppeteerController
Param
Type
Description
identifier
symbol
Unique identifier for a page connection.
proxy
string | object
Proxy to use in the current page. Must begin with a protocol e.g. http://, https://, socks://.

PuppeteerController.enableDebugMode(identifier)

Display console.log messages in environments different than Production.
Kind: static method of PuppeteerController
Param
Type
Description
identifier
symbol
Unique identifier for a page connection.

MonitorManager

Log on each of the subscribed monitoring tools.
Kind: global class

MonitorManager.log(report)

Register a report.
Kind: static method of MonitorManager
Param
Type
Description
report
object
Information to be logged in.

MonitorManager.subscribe(logger)

Subscribe to a monitoring or logging tool.
Kind: static method of MonitorManager
Param
Type
Description
logger
object
Monitoring or logging tool.

MonitorManager.unsubscribe(logger)

Unsubscribe to a monitoring or logging tool.
Kind: static method of MonitorManager
Param
Type
Description
logger
object
Monitoring or logging tool.

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
Param
Type
Description
report
object
Information that will be used to compose the report.

Sentry

Provides an interface for Sentry integration with Puppeteerist.
Kind: global class

Sentry.initialize(options, tags)