local assert = require("luassert") local type Node = require("types.Node") local scraper = require("scraper.module_doc") local get_doc_from_page = scraper.get_doc_from_page describe("Scrap documentation", function() it("should return a valid AST for an empty module", function() local ast , nodes = get_doc_from_page("", "empty") local expected : Node = { children = { { children = {}, name = "Signal", token = "enum", } }, name = "Empty", token = "module", } assert.same(expected, ast) assert.same({}, nodes) end) it("should produce Variable and `property::` Signal nodes", function() local ast = get_doc_from_page([[

Object properties

馃敆 value number 路 1 signal

Constraints:

Default value : 0
Negative allowed : true
]], "property_signal") local expected : Node = { children = { { children = { { name = "property::value", token = "identifier", }, }, name = "Signal", token = "enum", }, { name = "value", types = { "number" }, token = "variable", } }, name = "Property_signal", token = "module", } assert.same(expected, ast) end) it("should produce Enum nodes when an Object Property type is a String with constraints", function() local ast = get_doc_from_page([[

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") local expected : Node = { 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", token = "module", } assert.same(expected, ast) end) it("should produce a `string` typed Variable node when a String Property has no constraint", function() local ast = get_doc_from_page([[

Object properties

馃敆 markup string 路 1 signal
string
]], "property_string") local expected : Node = { children = { { children = { { name = "property::markup", token = "identifier", }, }, name = "Signal", token = "enum", }, { name = "markup", types = { "string" }, token = "variable", } }, name = "Property_string", token = "module", } assert.same(expected, ast) end) it("should provide a Function node with the `self` as the first positional parameter", function() local ast = get_doc_from_page([[

Object methods

馃敆 :swap (tag2)

Parameters:

Name Type(s) Description
tag2 tag The second tag
]], "awful.tag") local expected : Node = { 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", token = "module", } assert.same(expected, ast) end) it("should produce Signal nodes", function() local ast = get_doc_from_page([[

Signals

馃敆 widget::layout_changed 路 Inherited from wibox.widget.base
馃敆 widget::redraw_needed 路 Inherited from wibox.widget.base
]], "signal") local expected : Node = { children = { { children = { { name = "widget::layout_changed", token = "identifier", }, { name = "widget::redraw_needed", token = "identifier", }, }, name = "Signal", token = "enum", }, }, name = "Signal", token = "module", } assert.same(expected, ast) end) it("should produce Function nodes", function() local ast = get_doc_from_page([[

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 local expected : Node = { 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", token = "module", } assert.same(expected, ast) end) -- TODO : Fix the code then come back to this test, the current implementation is incomplete -- it("should produce a Record node when the function parameter is a table", function() -- local ast = get_doc_from_page([[ --

-- Static module functions --

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

Parameters:

-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
NameType(s)DescriptionDefault value
argsOptional -- table -- Undefined
clientOptional -- boolean -- -- Use the client screen instead of the mouse screen. -- -- false --
mouseOptional -- boolean -- Use the mouse screen -- true --
--

Returns:

--
    -- optional -- screen -- The focused screen object, or -- nil -- in case no screen is present currently. --
--
--
-- ]], "awful.screen") -- print(require("inspect")(ast)) -- assert.same(ast, { -- children = { -- { -- children = {}, -- name = "Signal", -- token = "enum", -- }, -- { -- parameters = { -- { -- children = { -- { -- types = { "boolean" }, -- name = "client", -- token = "variable", -- }, -- { -- types = { "boolean" }, -- name = "mouse", -- token = "variable", -- }, -- }, -- name = "Args", -- token = "record", -- }, -- { -- types = { "Focused_Args" }, -- name = "args", -- token = "variable", -- }, -- }, -- return_types = { "screen" }, -- name = "focused", -- token = "function", -- }, -- }, -- name = "Screen", -- token = "module", -- }) -- end) it("should return Function nodes with the `other_nodes` list when the function module name doesn't match the module name", function() local ast , other_nodes = get_doc_from_page([[

Static module functions

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

Returns:

    integer The number of client objects alive.
]], "awful.client") local expected_ast : Node = { children = { { children = {}, name = "Signal", token = "enum", }, }, name = "Client", token = "module", } assert.same(expected_ast, ast) local expected_other_nodes : { Node } = { { parameters = {}, return_types = { "integer" }, name = "client.instances", token = "function", } } assert.same(expected_other_nodes, other_nodes) end) end)