Lua Development Tools

User Area

Developer Area

For testing generated documentation, we have to browse generated document structure.

Prerequisites

I am pretty sure there a lib out there filling our needs, its caracteristics:

  • Enabling to browse document like a tree
  • No data loss (contain all data from generated document, no data loss)
  • Pure lua (so no native fragments)

Dependecy

Browsing the web, I found that LuaXML might be a good choice. It was described as rubust and pure lua on lua-l. Unfortunately its last version is not pure Lua and require C compilation. So instead to downgrade to pure Lua version, I had a look at Simple Lua XML Parser on Github. It is inpired by pure Lua implementations of Lua XML and fill our needs.

Sample of XML manipulations

Here is a quick samble of how it could be use to check output HTML structure. 

--
-- This library does not allow us to valid XML it is just made browsable as a
-- Lua table.
--
local xmlparser = require('xmlSimple').newParser()
local htmlsample = [[
<html>
<h1>Module name</h1>
<table>
    <tr><td> <a>fieldname</a>    </td><td> Field description.    </td></tr>
    <tr><td> <a>functionname</a> </td><td> Function description. </td></tr>
</table>
<h2>Fields</h2>
<h3>fieldname</h3>
Field description.
<h3>functionname</h3>
Function description.
</html>
]]

-- Parse HTML
local htmltable = xmlparser:ParseXmlText(htmlsample)

--
-- Analyze results
--
local typeelementcount = 2

-- One title
assert(htmltable.html.h1 and #htmltable.html.h1 == 0,
    'No single title in generated html.')

-- As many lines as type elements
assert(htmltable.html.table and #htmltable.html.table:children() == typeelementcount,
    'Description table contains wrong line count.')

-- As many detailed descriptions as type elements
assert(htmltable.html.h3 and #htmltable.html.h3 == typeelementcount,
    'Wrong type element count.')

How to test

We can either check areas of the document or valid the entire XML table.

Check areas of document

Really, it is what is done in the code sample above. Generate a XML tree from generated HTML and then analyze specific parts of it. We could improve navigation syntax in this style

local links = htmltable:filter('table'):first():children():filter('a'):children()

Check all document

It is like Testing ASTs. When we consider the parsing is stable, we create XML table from all tested Lua files. Then, we serialize this XML table and store in a file.

So now, testing consist in generating XML tables from same files and compared them to previously generated files. If there is a difference between XML tables, generated files are not the same.