Beginning. I'm a coder by trade. A few weeks ago I was setting up and needed to read its source to troubleshoot an error. Turns out it was written in go, perfect opportunity to start learning a new language! This is the story of building , an SBE framework written in golang. Vault conthego I find it's more fun and effective to learn something by actually using it in a project. I've been using for a while now and really like the idea of free-form executable specifications (spec). A spec is a collection of example scenarios (ex. given/when/then structure) written in plain language, usually in Markdown. Concordion The spec is backed by fixture code which, when executed, will mark assertions in the spec as either passed or failed (html reporting showing green or red respectively). A quick search tells me nothing like this has been done in go yet so project candidate sorted. To start, I worked my way through the golang to learn the basics. Googling for existing tooling that helps in language conversion from Java to Go gave me nothing but did lead to an excellent article - " ". tour Lessons learned porting 50k loc from Java to Go My main takeaway was the idea of iterative testing and validation after every little step. I entertained the thought (and did some reading) of AST transforms using antlr but that got me nowhere. Ideation and initial reading was from Saturday-Monday, May 9-11, around 12 hours effort. Iterations. Setup and preparation. Before I can get started on the first test there was the usual required project bootstrapping. I've got Intellij Idea for an IDE, decided on github as repo, and elected to just manage tasks in-project as a list of things to do in markdown. One of the main pre-requisites was to be able to parse markdown and convert it to xhtml. is the best library for that. However I realised during my initial stab that it wasn't able to render link titles with parentheses (which, like Concordion, was to be my mechanism for adding commands in markdown). The library being opensource though, a couple of nights and rounds of PR reviews later, it was ready for prime time (kudos to its maintainers). Go markdown This was over Tuesday-Wednesday, May 12-13, around 8 hours effort. First test, running a fixture method that spits out "Hello World!". Talk about biting off more than you can chew. First up was xml parsing the spec (now in the form of xhtml) into generic nodes, not standard but still pretty straightforward. What I didn't foresee was that I'd need to be diving into Go reflection this early (specs contain only strings, the call to something like "HelloWorld()" needs to be deconstructed and resolved to the relevant fixture function via reflection). Aside from the official docs, was my friend. Given a standard library function, it searches Go projects in github and shows you how the function is used. This proved to be an invaluable resource. With the large kubernetes codebase written in Go, there's a lot of examples to learn from. Also I've had to cast my mind back over a couple of decades during my C programming days to get the brain comfortable with pointers again. All up it was 3 days before first commit late on Saturday the 16th, with that first test working, around 16 hours effort. gowalker With the first test under my belt it's time to put the design hat on and think carefully about the commands that conthego will be supporting. These commands are the main interface for consumers using the tool so it pays to put enough upfront investment into them to make them simple and elegant to use. I was under no illusion I'll get everything perfectly right but I was conscious that I needed to start with a 'good set'. An hour of writing and rewriting got me the command set below. Apart from the one using literal parameters, the rest have stood the test of time (a couple of weeks!). Early on I decided to stick close to what Concordion already offers. Deviations were mostly for ease of parsing. Command prefixes were a single special character and (if required) appear only at the start of the command instruction string. set [World](- "var1") echo [](- "$var1") [](- "$var1.prop2") exec [](- "Hello()") [](- "var1=Hello(TEXT)") [](- "var2=Hello(var1)") [](- "var1=Hello('literal')") assert equals or isTrue [World](- "?Hello()") [World](- "?var1") Next lot of functions was to implement variable setting, function parameter passing, echoing of results, inline TEXT processing, and rudimentary dot navigation for struct properties. Of these, dot navigation proved to be a quite tricky as there was no implementation yet in Go. I rejected the notion of writing one, even the most basic, until my google foo led to the wonderful . OGNL go-dotnotation The trick was to marshal my structs into json then unmarshal them back into a generic tree of json nodes, which go-dotnotation can navigate. Simple and sufficient for my usecase. At this point, passing structs and slices around, it took a fair bit of pointer wrangling to fix some gnarly bugs (I understood the issues then but am sure I'd need to keep re-learning pointer semantics). This lot was part Saturday and most of Sunday, the 17th, at least 8 hours effort. Next up was execute-rows - executing a set of commands (specified on table headers) over each row of a table. Turning things around my head on how to make it work, I've come to appreciate the beauty of sequential processing of commands: top to bottom, left to right; a perfect match for depth-first traversal of the xhtml node tree. This meant binning some future (complex) usecases that don't fit the model but I was quite happy in exchange to keep functionality limited and simple. I introduced pre-processing which can transform commands in the xhtml nodes prior to the command collector collecting them for execution. In this case 'transform' means removing the command instructions from the table headers and distributing them to the actual data rows. This was Monday night, the 18th, 4 hours effort. Verify-rows - there are two variants: first is verifying a simple list of strings, the second verifying a list of structs. This got me back to the drawing board (to be honest, I'm still not fully sold on the solution I came up with thus these commands are currently experimental). In the end I decided to constrain the implementation to support only unstructured lists for the first case, and a table for the second. I needed to disambiguate the intent for list-processing from the regular commands. The top options were to introduce a new type of token in the command instruction string to signal list processing (ex. square brackets in "?listOfNames[]") or to introduce a new command that would impact processing of the succeeding commands. directive I opted for the latter for the reasons stated below. Implementation of verification for a list of strings was Tuesday night, 19th, 4 hours effort. to keep command instruction strings simple because there already was prior art - a directive command '!ExpectedToFail' which impacted succeeding assertions I considered list-processing to be 'advanced' commands and merited 'signaling' via use of a directive Verification for a list of structs is next, with support limited to being applied on a table. A major design decision here is to be able to choose for each column a specific struct property to assert on or echo. You can use echo exclusively (without asserts) for usecases like displaying a table of reference/config items. This was Wednesday night, 20th, 4 hours effort. I wanted to encourage easy usage, in case anyone would be keen to try, Tidying up of the basic command examples and the README file was Thursday night 21st, 4 hours effort. I've counted 60 hours above. I'm writing this on Sunday night, 24th, 4 hours effort. I'm a programmer, a serial optimist when it comes to estimates; and 64 is a nice round power of 2. Ending. The decision to store the task backlog as a TODO list in Markdown has proven to be handy. It felt natural to keep maintaining it whilst implementing code, all in the IDE. This worked as it was only me working on the codebase. Add another person and I'd probably look for a lightweight board like Trello. Being able to tick off items (or multiple) on something like a nightly basis builds up confidence and a sense of satisfaction. I've found that living documentation in the form of executable specifications are extremely useful in understanding how a system works. I always make it a point to refer to these artifacts primarily as specs rather than tests. Specs should be able to stand on their own even without having been executed. Crafting useful specs takes effort and time from the whole team with the main rewards being shared understanding, increased confidence that the system behaves as expected, and having something like a jumpstart tool for new team members. The Concordion documentation is the best resource describing how to write good specs. It's been fun learning and creating something new, and there's still a lot of TODOs to slowly nibble at. But now I feel I've been neglecting my books :) Enjoy! https://github.com/fanovilla/conthego Commit timeline: b0 Thu May : : + fix README.md b491b Thu May : : + Merge pull request # fanovilla/feature/tidy-examples a09c7 Thu May : : + better echo tests Thu May : : + better assert- test cadc82e Thu May : : + better assert-equals test af7442 Wed May : : + reorder backlog c2a03d6 Wed May : : + actor spec pre-processing routines a3622a Wed May : : + use concordion css dc272a Wed May : : + implement verify table rows d58b7 Wed May : : + implement verify rows list of s ea5cf4d Tue May : : + add reporting of date time generated directives c6fa62e Mon May : : + implement execute rows df56ffd Sun May : : + simplify run spec hook d3de448 Sun May : : + update todos cc Sun May : : + fail on panic c83b22 Sun May : : + implement slice eee8 Sun May : : + implement assert ea8d27 Sun May : : + Create LICENSE.txt f8c59 Sun May : : + implement map values; failed assert fails test; ExpectedToFail directive fbf8cca Sun May : : + implement struct values; dot.navigation b76e Sun May : : + implement TEXT substitution; assign execute result to var de4 Sun May : : + implement echo a953e87 Sun May : : + rename ReflectUtils to MethodCaller d3a5f Sun May : : + implement variable setting parameter passing d22215 Sat May : : + Initial commit 09874 21 23 14 22 2020 1200 77 21 22 57 56 2020 1200 1 from 78 21 22 53 24 2020 1200 set and 290460f 21 22 31 13 2020 1200 true 21 21 51 21 2020 1200 5 20 22 28 45 2020 1200 20 22 16 01 2020 1200 ref out 1 20 22 13 04 2020 1200 3 20 22 00 47 2020 1200 83 20 00 33 50 2020 1200 for string 19 18 38 59 2020 1200 and 18 23 50 44 2020 1200 17 23 17 14 2020 1200 17 23 03 18 2020 1200 12425 17 22 53 17 2020 1200 0 17 22 34 09 2020 1200 return 620 17 22 08 05 2020 1200 true 5 17 21 30 29 2020 1200 2f 17 20 40 03 2020 1200 return 17 19 45 15 2020 1200 return 613 17 16 51 12 2020 1200 8961 17 14 47 20 2020 1200 17 01 09 23 2020 1200 06 17 01 03 33 2020 1200 and 5 16 23 13 56 2020 1200
