local assert = require("luassert") local type Node = require("awesomewmdtl.types.Node") local scraper = require("awesomewmdtl.scraper.module_doc") local get_doc_from_page = scraper.get_doc_from_page local function test(html: string, module_path: string, expected_ast: Node, expected_other_nodes: { Node } | nil): function() return function() local ast , other_nodes = get_doc_from_page(html, module_path) assert.same(expected_ast, ast) assert.same(expected_other_nodes or {}, other_nodes) end end describe("Scrap documentation", function() it("should return a valid AST for an empty module", test( "", "empty", { children = { { children = {}, name = "Signal", token = "enum", } }, name = "Empty", module_path = "empty", dependencies = {}, token = "module", })) it("should produce Variable and `property::` Signal nodes", test( [[

Object properties

馃敆 value number 路 1 signal

Constraints:

Default value : 0
Negative allowed : true
]], "property_signal", { children = { { children = { { name = "property::value", token = "identifier", }, }, name = "Signal", token = "enum", }, { name = "value", types = { "number" }, token = "variable", } }, name = "Property_signal", module_path = "property_signal", dependencies = {}, token = "module", })) it("should produce Enum nodes when an Object Property type is a String with constraints", test( [[

Object properties

馃敆 horizontal_fit_policy string 路 1 signal
Default value : "auto"
Valid values:
"auto" : Honor the resize variable and preserve the aspect ratio.
"none" : Do not resize at all.
"fit" : Resize to the widget width.
]], "property_enum", { children = { { children = { { name = "property::horizontal_fit_policy", token = "identifier", }, }, name = "Signal", token = "enum", }, { children = { { name = "auto", token = "identifier", }, { name = "none", token = "identifier", }, { name = "fit", token = "identifier", }, }, name = "Horizontal_fit_policy", token = "enum", }, { name = "horizontal_fit_policy", types = { "Horizontal_fit_policy" }, token = "variable", }, }, name = "Property_enum", module_path = "property_enum", dependencies = {}, token = "module", })) it("should produce a `string` typed Variable node when a String Property has no constraint", test( [[

Object properties

馃敆 markup string 路 1 signal
string
]], "property_string", { children = { { children = { { name = "property::markup", token = "identifier", }, }, name = "Signal", token = "enum", }, { name = "markup", types = { "string" }, token = "variable", } }, name = "Property_string", module_path = "property_string", dependencies = {}, token = "module", })) it("should provide a Function node with the `self` as the first positional parameter", test( [[

Object methods

馃敆 :swap (tag2)

Parameters:

Name Type(s) Description
tag2 tag The second tag
]], "awful.tag", { children = { { children = {}, name = "Signal", token = "enum", }, { parameters = { { types = { "Tag" }, name = "self", token = "variable", }, { types = { "tag" }, -- This needs to be fixed : tag -> Tag name = "tag2", token = "variable", } }, return_types = {}, name = "swap", token = "function", }, }, name = "Tag", module_path = "awful.tag", dependencies = {}, token = "module", })) it("should produce Signal nodes", test( [[

Signals

馃敆 widget::layout_changed 路 Inherited from wibox.widget.base
馃敆 widget::redraw_needed 路 Inherited from wibox.widget.base
]], "signal", { children = { { children = { { name = "widget::layout_changed", token = "identifier", }, { name = "widget::redraw_needed", token = "identifier", }, }, name = "Signal", token = "enum", }, }, name = "Signal", module_path = "signal", dependencies = {}, token = "module", })) it("should produce Function nodes", test( [[

Static module functions

馃敆 awesome.kill (pid, sig) -> boolean
Send a signal to a process.

Parameters:

Name Type(s) Description
pid integer Process identifier. 0 and negative values have special meaning. See man 3 kill.
sig integer Signal number. See awesome.unix_signal for a list of signals.

Returns:

    boolean true if the signal was successfully sent, else false
]], "awesome", -- The module name must be the same as the module name in the doc { children = { { children = {}, name = "Signal", token = "enum", }, { parameters = { { types = { "integer" }, name = "pid", token = "variable", }, { types = { "integer" }, name = "sig", token = "variable", }, }, return_types = { "boolean" }, name = "kill", token = "function", } }, name = "Awesome", module_path = "awesome", dependencies = {}, token = "module", })) it("should produce a Record node when a function parameter is a named-parameter-table", test( [[

Static module functions

馃敆 awful.screen.focused {[args]} -> nil or screen

Parameters:

Name Type(s) Description Default value
args Optional table Undefined
client Optional boolean Use the client screen instead of the mouse screen. false
mouse Optional boolean Use the mouse screen true

Returns:

    optional screen The focused screen object, or nil in case no screen is present currently.
]], "awful.screen", { children = { { children = {}, name = "Signal", token = "enum", }, { children = { { types = { "boolean" }, name = "client", token = "variable", }, { types = { "boolean" }, name = "mouse", token = "variable", } }, name = "Focused_Args", token = "record", }, { parameters = { { types = { "Focused_Args" }, name = "args", token = "variable", }, }, return_types = { "screen" }, name = "focused", token = "function", }, }, name = "Screen", module_path = "awful.screen", dependencies = {}, token = "module", })) it("should go back to a table typed parameter when the record is empty", test( [[

Static module functions

馃敆 gears.table.crush (target, source, raw) -> table

Parameters:

Name Type(s) Description Default value
target table The target table. Values from source will be copied into this table. Not applicable
source table The source table. Its values will be copied into target. Not applicable
raw Optional bool If true, values will be assigned with rawset. This will bypass metamethods on target. false

Returns:

    table The target table.
]], "gears.table", { children = { { children = {}, name = "Signal", token = "enum", }, { parameters = { { types = { "table" }, name = "target", token = "variable", }, { types = { "table" }, name = "source", token = "variable", }, { types = { "bool" }, name = "raw", token = "variable", } }, return_types = { "table" }, name = "crush", token = "function", } }, name = "Table", module_path = "gears.table", dependencies = {}, token = "module", })) it("should go back to a table typed parameter when the record is empty and it's the last parameter", test( [[

Object methods

馃敆 :tags (tags_table) -> table 路 1 signal

Parameters:

Name Type(s) Description
tags_table table A table with tags to set, or nil to get the current tags.

Returns:

    table A table with all tags.
]], "awful.client", { children = { { children = {}, name = "Signal", token = "enum", }, { parameters = { { types = { "Client" }, name = "self", token = "variable", }, { types = { "table" }, name = "tags_table", token = "variable", }, }, return_types = { "table" }, name = "tags", token = "function", }, }, name = "Client", module_path = "awful.client", dependencies = {}, token = "module", })) it("should return Function nodes with the `other_nodes` list when the function module name doesn't match the module name", test( [[

Static module functions

馃敆 client.instances () -> integer
Get the number of instances.

Returns:

    integer The number of client objects alive.
]], "awful.client", { children = { { children = {}, name = "Signal", token = "enum", }, }, name = "Client", module_path = "awful.client", dependencies = {}, token = "module", }, { { parameters = {}, return_types = { "integer" }, name = "client.instances", token = "function", } })) end)