HookTest API Documentation

Library Structure

The library is divided in three different modules : - cmd is the module for running HookTest in command line. - test is the module for the main pipeline : it takes care of finding the files to test, dispatchinmg the test on them and interpret them - units is the module for each specific filetype test : it contains the logic of tests for individual files

Commands

HookTest.cmd.parse_args(args)

Parsing function. Written to support unit test

Parameters:args – List of command line argument Returns:Parsed argument

HookTest.cmd.cmd()

Run locally the software. Should not be called outside of a python cmd.py call

Test Pipeline

Files Finders

class HookTest.test.DefaultFinder(**options)

Finder are object used in Test to retrieve the target files of the tests

find(directory)

Return object to find

Parameters:directory – Root Directory to search in Returns:Path of xml text files, Path of __cts__.xml files Return type:(list, list)

class HookTest.test.FilterFinder(include, **options)

FilterFinder provide a filtering capacity to DefaultFinder.

It takes an include option which takes the form of the work urn (ie. in urn:cts:latinLit:phi1294.phi002.perseus-lat2 this would be phi1294.phi002.perseus-lat2, cut at any of the points : phi1294, phi1294.phi002, phi1294.phi002.perseus-lat2)

Parameters:include (str) – Representation of the work urn component (might be from one member down to the version member)

find(directory)

Return object to find

Parameters:directory – Root Directory to search in Returns:Path of xml text files, Path of __cts__.xml files Return type:(list, list)

Pipeline

class HookTest.test.Test(path, workers=1, scheme='auto', verbose=0, ping=None, secret='', triggering_size=None, console=False, build_manifest=False, finder=<class 'HookTest.test.DefaultFinder'>, finderoptions=None, countwords=False, allowfailure=False, from_travis_to_hook=False, timeout=30, guidelines=None, **kwargs)

Create a Test object

Parameters:

• path (str) – Path where the test should happen
• workers (str) – Number of simultaneous workers to be used
• scheme (str) – Name of the scheme
• verbose (int) – Log also rng and unit logs details
• ping (str) – URI to ping with data
• console (bool) – If set to true, print logs to the console
• finder (DefaultFinder) – Test files retriever
• finderoptions (dict) – Dictionary of option to instantiate specific finders
• countwords (bool) – Enable counting words for text tests (False by default)

cover(name, test, testtype=None, logs=None, additional=None)

Given a dictionary, compute the coverage of one item

Parameters:

• name –
• test (boolean) – Dictionary where keys represents test done on a file and value a boolean indicating passing status
• logs (list) – List of logs for one unit
• testtype (str) – the type of file tested (e.g., CTSMetadata or CTSText)

Returns:

Passing status

Return type:

dict

create_manifest()

Creates a manifest.txt file in the source directory that contains an ordered list of passing files

directory

Directory :return: Path of the full directory :rtype: str

download()

Information to send or print during download

end()

Deal with end logs

find()

Find CTS files in a directory :param directory: Path of the directory :type directory: str

Returns:Path of xml text files, Path of __cts__.xml files Return type:(list, list)

flush(stack)

Flush the remaining logs to the endpoint

json

Get Json representation of object report

Returns:JSON representing the complete test Return type:

log(log)

Deal with middle process situation

Parameters:log (UnitLog) – Result of a test for one unit Returns:None

middle()

to print out the results for the metadata files that failed the tests

Returns: Return type:

report

Get the report of the Test :return: Report of the test :rtype: dict

run()

Run the tests

Returns:Status of the test, List of logs, Report Return type:(string, list, dict)

send(data)

Send data to self.ping URL

Parameters:data – Data to send Returns:Result of request

send_to_hook_from_travis(texts_total, texts_passing, metadata_total, metadata_passing, coverage, nodes_count, words_dict=None)

Send data to travis

Returns:Request output

stack

Get the current stack of unsent item

Returns:Unset UnitLog Return type:[UnitLog]

start()

Deal with the start of the process

status

Updated the status string based on available informations

Returns:Status string updated Return type:str

successes

Get the number of successful tests

Returns:Number of successful tests Return type:int

triggering_size

Returns:

unit(filepath)

Do test for a file and print the results

Parameters:filepath (str) – Path of the file to be tested Returns:A UnitLog Return type:UnitLog

HookTest.test.cmd(console=False, **kwargs)

Generate the complete process of Test

Parameters:

• console (bool) – Print logs to console
• kwargs (dict) – Named arguments

Returns:

Status of the test

Models

class HookTest.test.UnitLog(directory, name, units, coverage, status, testtype=None, logs=None, sent=False, additional=None)

Model for logging information

Parameters:

• name – Name of the tested unit
• units –
• coverage – Percentage of successful tests
• status – Status of the unit
• logs – Logs
• sent – Status regarding the logging
• additional – Additional informations. Can be used for words counting

dict

Get the dictionary version of the object

Returns:Dictionary representation of the object Return type:dict

Test units

class HookTest.units.TESTUnit(path)

TestUnit Metaclass

Parameters:path – path of the current file

parsable()

Check and parse the xml file

Returns:Indicator of success and messages Return type:boolean

static rng(line)

Return a rng free line

Parameters:line – Line of logs Returns:LineColumn code, Error Return type:(str, str)

static rng_logs(logs)

Return a rng free line

Parameters:logs (str or bytes) – Sum of logs Returns:LineColumn code, Error Return type:(str, str)

class HookTest.capitains_units.cts.CTSMetadata_TestUnit(*args, **kwargs)

CTS testing object

Parameters:

path (basestring) – Path to the file

Variables:

• tests – Contains the list of methods to be run again the text
• readable – Human friendly string associated to object methods
• urns – List of URN retrieved in the file.
• type – Type of metadata (textgroup or work)

Shared variables with parent class:

Variables:

• path – Path for the resource
• xml – XML resource, parsed in python. Used to do general checking

Note

All method in CTSText_TestUnit.tests (“parsable”, “capitain”, “metadata”, “check_urns”, “filename” ) yield at least one boolean (might be more) which represents the success of it.

capitain()

Load the file in MyCapytain

check_urns()

Check the validity and presence of urns in the text

Note

Populates self.urns

filename()

Check the filename and the path correctly represent the path

metadata()

Check the presence of all metadata

test()

Test a file with various checks

Returns:List of urns Return type:list.<str>

class HookTest.capitains_units.cts.CTSText_TestUnit(path, countwords=False, timeout=30, *args, **kwargs)

CTS testing object

Parameters:

• path (basestring) – Path to the file
• countwords (bool) – Count the number of words and log it if necessary

Variables:

• tests – Contains the list of methods to be run again the text
• readable – Human friendly string associated to object methods
• inv – List of URN retrieved in metadata. Used to check the availability of metadata for the text
• scheme – Scheme to be used to check the
• Text – Text object according to MyCapytains parsing. Used to find passages

Shared variables with parent class:

Variables:

• path – Path for the resource
• xml – XML resource, parsed in python. Used to do general checking

Note

All method in CTSText_TestUnit.tests ( “parsable”, “has_urn”, “naming_convention”, “refsDecl”, “passages”, “unique_passage”, “inventory” ) yield at least one boolean (might be more) which represents the success of it.

count_words()

Count words in a file

duplicate()

Detects duplicate references

empty()

Detects empty references

epidoc()

Check the original file against Epidoc rng through a java pipe

forbidden()

Checks for forbidden characters in references

get_remote_rng(url)

Given a valid URL, downloads the RNG from the given URL and returns the filepath and name

Parameters:url – the URL of the RNG Returns:filenpath and name where the RNG was saved

has_urn()

Test that a file has its urn according to CapiTainS Guidelines in its scheme

inventory()

Check the naming convention of the file

language()

Tests to make sure an xml:lang element is on the correct node

local_file()

Check the original file against TEI rng through a java pipe

naming_convention()

Check the naming convention of the file

parsable()

Chacke that the text is parsable (as XML) and ingest it through MyCapytain then.

Note

Override super(parsable) and add CapiTainS Ingesting to it

passages()

Check that passages are available at each level. On top of that, it checks for forbidden characters and duplicate in references

refsDecl()

Check that the text contains refsDecl informations

run_rng(rng_path)

Run the RNG through JingTrang

Parameters:rng_path – Path to the RelaxNG file to run against the XML to test

tei()

Check the original file against TEI rng through a java pipe

test(scheme, guidelines, rng=None, inventory=None)

Test a file with various checks

Parameters:

• scheme (str) – Test with TEI DTD
• inventory (list) – URNs to be matched against

Returns:

Iterator containing human readable test name, boolean status and logs

Return type:

iterator(str, bool, list(str))

unique_passage()

Check that citation scheme do not collide (eg. Where text:1 would be the same node as text:1.1)