Category Archives: StaticTea

Statictea template system

Statictea Dependencies Graphs

Posted on by

Statictea has two types of dependency graphs, the module dependencies and the nim system module dependencies. You can learn a lot about a project from its dependencies.

Below is the link to the statictea’s source code documentation. The module dependency graph is at the top. If you scroll down to the bottom you see the nim system module dependency graph. If you are viewing on a phone, you can pinch zoom to see more detail.

statictea’s source code docs

Module Dependencies

A graph node represents a nim source code module (file). The lines connecting the nodes show the dependencies. For example the parseCommandLine module on the left depends on the cmdline module.

From the module dependency graph you can see:

  • which modules you can share with other projects
  • the frequently used modules
  • the relative module file sizes
  • the project entry point
  • the stand alone modules

It’s easier to edit and test modular code because of well defined and simple interfaces.

The green nodes do not depend on any module. These are the modules you can easily share with other projects.

The red dependency line tells you that the module has only one dependency. I try to rework the code to remove the dependency if feasible. The opresult and matches modules are example of this.

If you put all your code in one module, it wouldn’t have any dependencies! However it would be to bloated and not granular enough for sharing with other projects. You can tell the relative size of a module by the size of its node. runCommand is the biggest module.

The comparelines, jsondocraw and stfrunner modules are stand alone commands so they are not connected in this graph.

Nim Module Graph

The nim module graph at the bottom of the page tells you the nim language APIs you need. It shows which nim modules are used by which statictea modules.

The green nim modules are only used by one statictea module. I strive for green modules, that way all related functions are grouped together.

Often I wrap a nim module. The statictea wrapper module exposes a limited and simple interface tailored for statictea needs. This was done for the re module. The graph tells you that statictea only uses the regular expression functions in the regexes module and not the multitude of functions in the re module. The readjson module is another example of this.

Building Graphs

You build the dependency graph with the nimble task dotsrc and the nim module graph with dotsys. Search for createDependencyGraph and createDependencyGraph2 in the nimble file.

Each graph is an svg file. The graphviz program produces the file based on a text file defining the dependencies. The text file is created by the nimble task starting from the data generated by nim’s genDepend command.

* https://graphviz.org/

StfRunner

Posted on by

The stfRunner command is used for running statictea system tests.

StfRunner executes a stf test file which tests a feature. A stf file contains instructions for creating files, running files and comparing files.

A normal test creates all the input files, runs statictea then compares the outputs to the expected values.

Although stfRunner was written to test statictea, you can use it to test any command line program.

What’s cool about it:

* you specify each test in one file
* a test with its documentation looks good in a markdown reader
* the test file format is simple
* you can test standard out, standard error, the error code as well as files

Below is the hello world statictea readme example. The test creates four files “cmd.sh”, “hello.json”, “hello.html” and “stdout.expected”. It then runs the cmd.sh file which creates two output files: “stdout” and “stderr”. The final steps compare the output files with the expected files.

stf file, version 0.1.0

# Hello World

Readme Hello World example.

### File cmd.sh command

~~~
$statictea \
-s hello.json \
-t hello.html \
>stdout 2>stderr
~~~

### File hello.html

~~~
hello {s.name}
~~~

### File hello.json

~~~
{"name": "world"}
~~~

### File stdout.expected

~~~
hello world
~~~

### Expected stdout == stdout.expected
### Expected stderr == empty

In this example, six files where created. Using some other test method, it would be hard to manage all these files when you have a lot of tests.

Since the test file is a markdown file, you can create easy to read tests and associated embedded documentation and it looks good in a markdown reader. You can see what hello world it looks like viewed with github’s viewer:

* hello.stf.md

Here are all the statictea system tests:

* statictea stf tests

I’m planning to spin out stfRunner into its own standalone github project.

The letters STF stand for “Single Test File” or my name STeve Flenniken.

I’m considering changing its name to tea-runner. You can think of it as t-runner for test-runner, stf-runner, or maybe rum-runner or beer-run.