Go to an URL. This is similar to entering an URL in a browser
address bar, pressing Enter and waiting until page loads.

Signature:ok,reason=splash.go{url,baseurl=nil,headers=nil}

Parameters:

url - URL to load;

baseurl - base URL to use, optional. When baseurl argument is passed
the page is still loaded from url, but it is rendered as if it was
loaded from baseurl: relative resource paths will be relative
to baseurl, and the browser will think baseurl is in address bar;

headers - a Lua table with HTTP headers to add/replace in the initial request.

Returns:ok,reason pair. If ok is nil then error happened during
page load; reason provides an information about error type.

Three types of errors are reported (ok can be nil in 3 cases):

There is nothing to render. This can happen if a host doesn’t exist,
server dropped connection, etc. In this case reason is "error".

Server returned a response with 4xx or 5xx HTTP status code.
reason is "http<code>" in this case, i.e. for
HTTP 404 Not Found reason is "http404".

localok,reason=splash:go("http://example.com")ifnotok:ifreason:sub(0,4)=='http'then-- handle HTTP errorselse-- handle other errorsendend-- process the page-- assert can be used as a shortcut for error handlingassert(splash:go("http://example.com"))

Errors (ok==nil) are only reported when “main” webpage request failed.
If a request to a related resource failed then no error is reported by
splash:go. To detect and handle such errors (e.g. broken image/js/css
links, ajax requests failed to load) use splash:har.

splash:go follows all HTTP redirects before returning the result,
but it doesn’t follow HTML <metahttp-equiv="refresh"...> redirects or
redirects initiated by JavaScript code. To give the webpage time to follow
those redirects use splash:wait.

headers argument allows to add or replace default HTTP headers for the
initial request. To set custom headers for all further requests
(including requests to related resources) use
splash:set_custom_headers.

User-Agent header is special: once used, it is kept for further requests.
This is an implementation detail and it could change in future releases;
to set User-Agent header it is recommended to use
splash:set_user_agent method.

cancel_on_redirect - if true (not a default) and a redirect
happened while waiting, then splash:wait stops earlier and returns
nil,"redirect". Redirect could be initiated by
<metahttp-equiv="refresh"...> HTML tags or by JavaScript code.

cancel_on_error - if true (default) and an error which prevents page
from being rendered happened while waiting (e.g. an internal WebKit error
or a network error like a redirect to a non-resolvable host)
then splash:wait stops earlier and returns nil,"error".

Returns:ok,reason pair. If ok is nil then the timer was
stopped prematurely, and reason contains a string with a reason.
Possible reasons are "error" and "redirect".

By default wait timer continues to tick when redirect happens.
cancel_on_redirect option can be used to restart the timer after
each redirect. For example, here is a function that waits for a given
time after each page load in case of redirects:

Lua strings, numbers, booleans and tables can be passed as arguments;
they are converted to JS strings/numbers/booleans/objects.
Currently it is not possible to pass other Lua objects. For example, it
is not possible to pass a wrapped JavaScript function or a regular Lua function
as an argument to another wrapped JavaScript function.

Lua → JavaScript conversion rules:

Lua

JavaScript

string

string

number

number

boolean

boolean

table

Object

nil

undefined

Function result is converted from JavaScript to Lua data type. Only simple
JS objects are supported. For example, returning a function or a
JQuery selector from a wrapped function won’t work.

JavaScript → Lua conversion rules:

JavaScript

Lua

string

string

number

number

boolean

boolean

Object

table

Array

table

undefined

nil

null

"" (an empty string)

Date

string: date’s ISO8601 representation, e.g. 1958-05-21T10:12:00Z

RegExp

table {_jstype='RegExp',caseSensitive=true/false,pattern='my-regexp'}

function

an empty table {} (don’t rely on it)

Function arguments and return values are passed by value. For example,
if you modify an argument from inside a JavaScript function then the caller
Lua code won’t see the changes, and if you return a global JS object and modify
it in Lua then object won’t be changed in webpage context.

Note

The rule of thumb: if an argument or a return value can be serialized
via JSON, then it is fine.

If a JavaScript function throws an error, it is re-throwed as a Lua error.
To handle errors it is better to use JavaScript try/catch because some of the
information about the error can be lost in JavaScript → Lua conversion.

splash:evaljs is useful for evaluation of short JavaScript snippets
without defining a wrapper function. Example:

localtitle=splash:evaljs("document.title")

Don’t use splash:evaljs when the result is not needed - it is
inefficient and could lead to problems; use splash:runjs instead.
For example, the following innocent-looking code (using jQuery) may fail:

splash:evaljs("$(console.log('foo'));")

A gotcha is that to allow chaining jQuery $ function returns a huge object,
splash:evaljs tries to serialize it and convert to Lua. It is a waste
of resources, and it could trigger internal protection measures;
splash:runjs doesn’t have this problem.

If the code you’re evaluating needs arguments it is better to use
splash:jsfunc instead of splash:evaljs and string formatting.
Compare:

Run asynchronous JavaScript code in page context. The Lua script will
yield until the JavaScript code tells it to resume.

Signature:result,error=splash:wait_for_resume(snippet,timeout)

Parameters:

snippet - a string with a JavaScript source code to execute. This code
must include a function called main. The first argument to main
is an object that has the properties resume and error. resume
is a function which can be used to resume Lua execution. It takes an optional
argument which will be returned to Lua in the result.value return value.
error is a function which can be called with a required string value
that is returned in the error return value.

timeout - a number which determines (in seconds) how long to allow JavaScript
to execute before forceably returning control to Lua. Defaults to
zero, which disables the timeout.

Returns:result,error pair. When the execution is successful
result is a table. If the value returned by JavaScript is not
undefined, then the result table will contain a key value
that has the value passed to splash.resume(…). The result table also
contains any additional key/value pairs set by splash.set(…). In case of
timeout or JavaScript errors result is nil and error contains an
error message string.

Examples:

The first, trivial example shows how to transfer control of execution from Lua
to JavaScript and then back to Lua. This command will tell JavaScript to
sleep for 3 seconds and then return to Lua. Note that this is an async
operation: the Lua event loop and the JavaScript event loop continue to run
during this 3 second pause, but Lua will not continue executing the current
function until JavaScript calls splash.resume().

result is set to an empty table to indicate that nothing was returned
from splash.resume. You can use assert(splash:wait_for_resume(…))
even when JavaScript does not return a value because the empty table signifies
success to assert().

Note

Your JavaScript code must contain a main() function. You will get an
error if you do not include it. The first argument to this function can
have any name you choose, of course. We will call it splash by
convention in this documentation.

The next example shows how to return a value from JavaScript to Lua.
You can return booleans, numbers, strings, arrays, or objects.

As with splash:evaljs, be wary of returning objects that are
too large, such as the $ object in jQuery, which will consume a lot
of time and memory to convert to a Lua result.

You can also set additional key/value pairs in JavaScript with the
splash.set(key,value) function. Key/value pairs will be included
in the result table returned to Lua. The following example demonstrates
this.

The next example shows an incorrect usage of splash:wait_for_resume():
the JavaScript code does not contain a main() function. result is
nil because splash.resume() is never called, and error contains
an error message explaining the mistake.

The next example shows the effect of the timeout argument. We have set
the timeout argument to 1 second, but our JavaScript code will not call
splash.resume() for 3 seconds, which guarantees that
splash:wait_for_resume() will time out.

When it times out, result will be nil, error will contain a string
explaining the timeout, and Lua will continue executing. Calling
splash.resume() or splash.error() after a timeout has no effect.

Nothing prevents us from taking multiple HTML snapshots. For example, let’s
visit first 10 pages on a website, and for each page store
initial HTML snapshot and an HTML snapshot after waiting 0.5s:

-- Given an url, this function returns a table with-- two HTML snapshots: HTML right after page is loaded,-- and HTML after waiting 0.5s.functionpage_info(splash,url)localok,msg=splash:go(url)ifnotokthenreturn{ok=false,reason=msg}endlocalres={before=splash:html()}assert(splash:wait(0.5))-- this shouldn't fail, so we wrap it in assertres.after=splash:html()-- the same as res["after"] = splash:html()res.ok=truereturnresend-- visit first 10 http://example.com/pages/<num> pages,-- return their html snapshotsfunctionmain(splash)localresult={}fori=1,10dolocalurl="http://example.com/pages/"..page_numresult[i]=page_info(splash,url)endreturnresultend

scale_method - optional, method to use when resizing the image, 'raster'
or 'vector'

Returns: PNG screenshot data.

Without arguments splash:png() will take a snapshot of the current viewport.

width parameter sets the width of the resulting image. If the viewport has a
different width, the image is scaled up or down to match the specified one.
For example, if the viewport is 1024px wide then splash:png{width=100} will
return a screenshot of the whole viewport, but the image will be downscaled to
100px width.

height parameter sets the height of the resulting image. If the viewport has
a different height, the image is trimmed or extended vertically to match the
specified one without resizing the content. The region created by such
extension is transparent.

To set the viewport size use splash:set_viewport_size,
splash:set_viewport_full or render_all argument. render_all=true
is equivalent to running splash:set_viewport_full() just before the
rendering and restoring the viewport size afterwards.

scale_method parameter must be either 'raster' or 'vector'. When
scale_method='raster', the image is resized per-pixel. When
scale_method='vector', the image is resized per-element during rendering.
Vector scaling is more performant and produces sharper images, however it may
cause rendering artifacts, so use it with caution.

If the result of splash:png() is returned directly as a result of
“main” function, the screenshot is returned as binary data:

Returns: information about pages loaded, events happened,
network requests sent and responses received in HAR format.

If your script returns the result of splash:har() in a top-level
"har" key then Splash UI will give you a nice diagram with network
information (similar to “Network” tabs in Firefox or Chrome developer tools):

splash:init_cookies({{name="baz",value="egg"},{name="spam",value="egg",domain="example.com"},{name="foo",value="bar",path="/",domain="localhost",expires="2016-07-24T19:20:30+02:00",secure=true,httpOnly=true,}})-- do somethingassert(splash:go("http://example.com"))

By default, images are enabled. Disabling of the images can save a lot
of network traffic (usually around ~50%) and make rendering faster.
Note that this option can affect the JavaScript code inside page:
disabling of the images may change sizes and positions of DOM elements,
and scripts may read and use them.

Splash uses in-memory cache; cached images will be displayed
even when images are disabled. So if you load a page, then disable images,
then load a new page, then likely first page will display all images
and second page will display some images (the ones common with the first page).
Splash cache is shared between scripts executed in the same process, so you
can see some images even if they are disabled at the beginning of the script.

This will relayout all document elements and affect geometry variables, such
as window.innerWidth and window.innerHeight. However
window.onresize event callback will only be invoked during the next
asynchronous operation and splash:png is notably synchronous, so if
you have resized a page and want it to react accordingly before taking the
screenshot, use splash:wait.

Returns: two numbers: width and height the viewport is set to, in pixels.

splash:set_viewport_full should be called only after page is loaded, and
some time passed after that (use splash:wait). This is an unfortunate
restriction, but it seems that this is the only way to make automatic resizing
work reliably.