tests.lib - Luakit

# Luakit Documentation / Modules / tests.lib

# Module `tests.lib`

Testing interface

This module provides useful functions for use in luakit tests.

## Functions

### tests.lib.wait_for_view (view)

Pause test execution until a webview widget finishes loading.

#### Parameters

- view
  Type: widget
  The webview widget to wait on.

### tests.lib.delay (timeout)

Pause test execution for a short time.

#### Parameters

- timeout
  Type: number
  Optional
  The time to delay, in milliseconds. Defaults to 5 milliseconds.

### tests.lib.wait_until (func, poll_time, timeout)

Pause test execution until a predicate returns `true`.

Suspends test execution, polling the provided predicate function at an interval, until the predicate returns a truthy value. If the predicate does not return a truthy value within a certain time period, the running test fails.

#### Parameters

- func
  Type: function
  The predicate function.
- poll_time
  Type: number
  Optional
  The interval at which to poll the predicate, in milliseconds. Defaults to 5 milliseconds.
- timeout
  Type: number
  Optional
  Maximum time to wait before failing the running test, in milliseconds. Defaults to 200 milliseconds.

### tests.lib.wait_for_signal (object, signal, timeout)

Pause test execution until a particular signal is emitted on an object.

Suspends test execution until `signal` is emitted on `object`. If no such signal is emitted on `object` within `timeout` milliseconds, the running test fails.

#### Parameters

- object
  Type: any type
  The object to wait for `signal` on.
- signal
  Type: string
  The signal to wait for.
- timeout
  Type: number
  Optional
  Maximum time to wait before failing the running test, in milliseconds. Defaults to 200 milliseconds.

### tests.lib.wait (timeout)

Pause test execution indefinitely.

The running test is suspended until `continue()` is called. If `continue()` is not called within `timeout` milliseconds, the running test fails.

#### Parameters

- timeout
  Type: number
  Optional
  Maximum time to wait before failing the running test, in milliseconds. Defaults to 200 milliseconds.

#### Return Values

- any type
  All parameters to `continue()`.

### tests.lib.continue (...)

Continue test execution.

The running test, currently suspended after a call to `wait()`, is resumed. `wait()` must have been previously called.

All parameters to `continue()` are returned by `wait()`.

#### Parameters

- ...
  Type: any type
  Values to return from `wait()`.

### tests.lib.http_server ()

Get the URI prefix for the test HTTP server.

The port the test server listens on may not always be the same. This function returns the current URI prefix, which looks like `http://127.0.0.1:8888/`.

Currently, however, there is no HTTP server; instead, the custom URI scheme `luakit-test://` is used.

#### Return Values

- string
  The URI prefix for the test HTTP server.

### tests.lib.find_files (dirs, patterns, excludes)

Retrieve a subset of files in the current directory.

This function searches the directory and then filters the result according to the provided parameters and the `.gitignore` file. It is mostly intended for use in code style tests. The returned list of file paths includes all files that:

- are within at least one of the directories in `dirs`,
- match at least one of the Lua patterns in `patterns`, and
- do not match any of the Lua patterns in `excludes`.

#### Parameters

- dirs
  Type: string or table
  The directory prefix (or list of prefixes) in which to look for files.
- patterns
  Type: string or table
  A Lua pattern (or list of patterns) with which to filter file paths; non-matching files are removed.
- excludes
  Type: table
  Optional
  A list of Lua patterns with which to filter file paths; matching files are removed.

#### Return Values

- table
  A list of matching file paths.

### tests.lib.format_file_errors (entries)

Helper function to format a list of file errors.

Aligns file names and file errors into two separate columns.

#### Parameters

- entries
  Type: {entry}
  A list of file error entries.

  #### `entry` format

  - file: The path of the file.
  - err: The error string.

#### Return Values

- string
  The formatted output string.

## Attribution

#### Copyright

- 2017 Aidan Holm