1 //: The goal of layers is to make programs more easy to understand and more
  2 //: malleable, easy to rewrite in radical ways without accidentally breaking
  3 //: some corner case. Tests further both goals. They help understandability by
  4 //: letting one make small changes and get feedback. What if I wrote this line
  5 //: like so? What if I removed this function call, is it really necessary?
  6 //: Just try it, see if the tests pass. Want to explore rewriting this bit in
  7 //: this way? Tests put many refactorings on a firmer footing.
  8 //:
  9 //: But the usual way we write tests seems incomplete. Refactorings tend to
 10 //: work in the small, but don't help with changes to function boundaries. If
 11 //: you want to extract a new function you have to manually test-drive it to
 12 //: create tests for it. If you want to inline a function its tests are no
 13 //: longer valid. In both cases you end up having to reorganize code as well as
 14 //: tests, an error-prone activity.
 15 //:
 16 //: In response, this layer introduces the notion of *domain-driven* testing.
 17 //: We focus on the domain of inputs the whole program needs to handle rather
 18 //: than the correctness of individual functions. All tests invoke the program
 19 //: in a single way: by calling run() with some input. As the program operates
 20 //: on the input, it traces out a list of _facts_ deduced about the domain:
 21 //:   trace("label") << "fact 1: " << val;
 22 //:
 23 //: Tests can now check these facts:
 24 //:   :(scenario foo)
 25 //:   34  # call run() with this input
 26 //:   +label: fact 1: 34  # 'run' should have deduced this fact
 27 //:   -label: fact 1: 35  # the trace should not contain such a fact
 28 //:
 29 //: Since we never call anything but the run() function directly, we never have
 30 //: to rewrite the tests when we reorganize the internals of the program. We
 31 //: just have to make sure our rewrite deduces the same facts about the domain,
 32 //: and that's something we're going to have to do anyway.
 33 //:
 34 //: To avoid the combinatorial explosion of integration tests, each layer
 35 //: mainly logs facts to the trace with a common *label*. All tests in a layer
 36 //: tend to check facts with this label. Validating the facts logged with a
 37 //: specific label is like calling functions of that layer directly.
 38 //:
 39 //: To build robust tests, trace facts about your domain rather than details of
 40 //: how you computed them.
 41 //:
 42 //: More details: http://akkartik.name/blog/tracing-tests
 43 //:
 44 //: ---
 45 //:
 46 //: Between layers and domain-driven testing, programming starts to look like a
 47 //: fundamentally different activity. Instead of a) superficial, b) local rules
 48 //: on c) code [like say http://blog.bbv.ch/2013/06/05/clean-code-cheat-sheet],
 49 //: we allow programmers to engage with the a) deep, b) global structure of the
 50 //: c) domain. If you can systematically track discontinuities in the domain,
 51 //: you don't care if the code used gotos as long as it passed the tests. If
 52 //: tests become more robust to run it becomes easier to try out radically
 53 //: different implementations for the same program. If code is super-easy to
 54 //: rewrite, it becomes less important what indentation style it uses, or that
 55 //: the objects are appropriately encapsulated, or that the functions are
 56 //: referentially transparent.
 57 //:
 58 //: Instead of plumbing, programming becomes building and gradually refining a
 59 //: map of the environment the program must operate under. Whether a program is
 60 //: 'correct' at a given point in time is a red herring; what matters is
 61 //: avoiding regression by monotonically nailing down the more 'eventful' parts
 62 //: of the terrain. It helps readers new and old, and rewards curiosity, to
 63 //: organize large programs in self-similar hierarchies of example scenarios
 64 //: colocated with the code that makes them work.
 65 //:
 66 //:   "Programming properly should be regarded as an activity by which
 67 //:   programmers form a mental model, rather than as production of a program."
 68 //:   -- Peter Naur (http://alistair.cockburn.us/ASD+book+extract%3A+%22Naur,+Ehn,+Musashi%22)
 69 
 70 :(before "End Types")
 71 struct trace_line {
 72   int depth;  // optional field just to help browse traces later
 73   string label;
 74   string contents;
 75   trace_line(string l, string c) :depth(0), label(l), contents(c) {}
 76   trace_line(int d, string l, string c) :depth(d), label(l), contents(c) {}
 77 };
 78 
 79 :(before "End Globals")
 80 bool Hide_errors = false;
 81 bool Dump_trace = false;
 82 string Dump_label = "";
 83 :(before "End Reset")
 84 Hide_errors = false;
 85 Dump_trace = false;
 86 Dump_label = "";
 87 
 88 :(before "End Types")
 89 // Pre-define some global constants that trace_stream needs to know about.
 90 // Since they're in the Types section, they'll be included in any cleaved
 91 // compilation units. So no extern linkage.
 92 const int Max_depth = 9999;
 93 const int Error_depth = 0;  // definitely always print errors
 94 const int App_depth = 2;  // temporarily where all Mu code will trace to
 95 
 96 struct trace_stream {
 97   vector<trace_line> past_lines;
 98   // accumulator for current line
 99   ostringstream* curr_stream;
100   string curr_label;
101   int curr_depth;
102   int callstack_depth;
103   int collect_depth;
104   ofstream null_stream;  // never opens a file, so writes silently fail
105   trace_stream() :curr_stream(NULL), curr_depth(Max_depth), callstack_depth(0), collect_depth(Max_depth) {}
106   ~trace_stream() { if (curr_stream) delete curr_stream; }
107 
108   ostream& stream(string label) {
109   ¦ return stream(Max_depth, label);
110   }
111 
112   ostream& stream(int depth, string label) {
113   ¦ if (depth > collect_depth) return null_stream;
114   ¦ curr_stream = new ostringstream;
115   ¦ curr_label = label;
116   ¦ curr_depth = depth;
117   ¦ return *curr_stream;
118   }
119 
120   // be sure to call this before messing with curr_stream or curr_label
121   void newline();
122   // useful for debugging
123   string readable_contents(string label);  // empty label = show everything
124 };
125 
126 :(code)
127 void trace_stream::newline() {
128   if (!curr_stream) return;
129   string curr_contents = curr_stream->str();
130   if (!curr_contents.empty()) {
131   ¦ past_lines.push_back(trace_line(curr_depth, trim(curr_label), curr_contents));  // preserve indent in contents
132   ¦ if ((!Hide_errors && curr_label == "error")
133   ¦ ¦ ¦ || Dump_trace
134   ¦ ¦ ¦ || (!Dump_label.empty() && curr_label == Dump_label))
135   ¦ ¦ cerr << curr_label << ": " << curr_contents << '\n';
136   }
137   delete curr_stream;
138   curr_stream = NULL;
139   curr_label.clear();
140   curr_depth = Max_depth;
141 }
142 
143 string trace_stream::readable_contents(string label) {
144   ostringstream output;
145   label = trim(label);
146   for (vector<trace_line>::iterator p = past_lines.begin();  p != past_lines.end();  ++p)
147   ¦ if (label.empty() || label == p->label) {
148   ¦ ¦ output << std::setw(4) << p->depth << ' ' << p->label << ": " << p->contents << '\n';
149   ¦ }
150   return output.str();
151 }
152 
153 :(before "End Globals")
154 trace_stream* Trace_stream = NULL;
155 int Trace_errors = 0;  // used only when Trace_stream is NULL
156 
157 :(before "End Includes")
158 #define CLEAR_TRACE  delete Trace_stream, Trace_stream = new trace_stream;
159 
160 // Top-level helper. IMPORTANT: can't nest
161 #define trace(...)  !Trace_stream ? cerr /*print nothing*/ : Trace_stream->stream(__VA_ARGS__)
162 
163 // Just for debugging; 'git log' should never show any calls to 'dbg'.
164 #define dbg trace(0, "a")
165 #define DUMP(label)  if (Trace_stream) cerr << Trace_stream->readable_contents(label);
166 
167 // Errors are a special layer.
168 #define raise  (!Trace_stream ? (scroll_to_bottom_and_close_console(),++Trace_errors,cerr) /*do print*/ : Trace_stream->stream(Error_depth, "error"))
169 // If we aren't yet sure how to deal with some corner case, use assert_for_now
170 // to indicate that it isn't an inviolable invariant.
171 #define assert_for_now assert
172 
173 //: Automatically close the console in some situations.
174 :(before "End One-time Setup")
175 atexit(scroll_to_bottom_and_close_console);
176 :(code)
177 void scroll_to_bottom_and_close_console() {
178   if (!tb_is_active()) return;
179   // leave the screen in a relatively clean state
180   tb_set_cursor(tb_width()-1, tb_height()-1);
181   cout << "\r\n";
182   tb_shutdown();
183 }
184 
185 // Inside tests, fail any tests that displayed (unexpected) errors.
186 // Expected errors in tests should always be hidden and silently checked for.
187 :(before "End Test Teardown")
188 if (Passed && !Hide_errors && trace_contains_errors()) {
189   Passed = false;
190 }
191 :(code)
192 bool trace_contains_errors() {
193   return Trace_errors > 0 || trace_count("error") > 0;
194 }
195 
196 :(before "End Types")
197 struct end {};
198 :(code)
199 ostream& operator<<(ostream& os, unused end) {
200   if (Trace_stream) Trace_stream->newline();
201   return os;
202 }
203 
204 :(before "End Globals")
205 bool Save_trace = false;
206 
207 // Trace_stream is a resource, lease_tracer uses RAII to manage it.
208 :(before "End Types")
209 struct lease_tracer {
210   lease_tracer();
211   ~lease_tracer();
212 };
213 :(code)
214 lease_tracer::lease_tracer() { Trace_stream = new trace_stream; }
215 lease_tracer::~lease_tracer() {
216   if (!Trace_stream) return;  // in case tests close Trace_stream
217   if (Save_trace) {
218   ¦ ofstream fout("last_trace");
219   ¦ fout << Trace_stream->readable_contents("");
220   ¦ fout.close();
221   }
222   delete Trace_stream, Trace_stream = NULL;
223 }
224 :(before "End Includes")
225 #define START_TRACING_UNTIL_END_OF_SCOPE  lease_tracer leased_tracer;
226 :(before "End Test Setup")
227 START_TRACING_UNTIL_END_OF_SCOPE
228 
229 :(before "End Includes")
230 #define CHECK_TRACE_CONTENTS(...)  check_trace_contents(__FUNCTION__, __FILE__, __LINE__, __VA_ARGS__)
231 
232 #define CHECK_TRACE_CONTAINS_ERRORS()  CHECK(trace_contains_errors())
233 #define CHECK_TRACE_DOESNT_CONTAIN_ERRORS() \
234   if (Passed && trace_contains_errors()) { \
235   ¦ cerr << "\nF - " << __FUNCTION__ << "(" << __FILE__ << ":" << __LINE__ << "): unexpected errors\n"; \
236   ¦ DUMP("error"); \
237   ¦ Passed = false; \
238   ¦ return; \
239   }
240 
241 #define CHECK_TRACE_COUNT(label, count) \
242   if (Passed && trace_count(label) != (count)) { \
243   ¦ cerr << "\nF - " << __FUNCTION__ << "(" << __FILE__ << ":" << __LINE__ << "): trace_count of " << label << " should be " << count << '\n'; \
244   ¦ cerr << "  got " << trace_count(label) << '\n';  /* multiple eval */ \
245   ¦ DUMP(label); \
246   ¦ Passed = false; \
247   ¦ return;  /* Currently we stop at the very first failure. */ \
248   }
249 
250 #define CHECK_TRACE_DOESNT_CONTAIN(...)  CHECK(trace_doesnt_contain(__VA_ARGS__))
251 
252 :(code)
253 bool check_trace_contents(string FUNCTION, string FILE, int LINE, string expected) {
254   if (!Passed) return false;
255   if (!Trace_stream) return false;
256   vector<string> expected_lines = split(expected, "^D");
257   int curr_expected_line = 0;
258   while (curr_expected_line < SIZE(expected_lines) && expected_lines.at(curr_expected_line).empty())
259   ¦ ++curr_expected_line;
260   if (curr_expected_line == SIZE(expected_lines)) return true;
261   string label, contents;
262   split_label_contents(expected_lines.at(curr_expected_line), &label, &contents);
263   for (vector<trace_line>::iterator p = Trace_stream->past_lines.begin();  p != Trace_stream->past_lines.end();  ++p) {
264   ¦ if (label != p->label) continue;
265   ¦ if (contents != trim(p->contents)) continue;
266   ¦ ++curr_expected_line;
267   ¦ while (curr_expected_line < SIZE(expected_lines) && expected_lines.at(curr_expected_line).empty())
268   ¦ ¦ ++curr_expected_line;
269   ¦ if (curr_expected_line == SIZE(expected_lines)) return true;
270   ¦ split_label_contents(expected_lines.at(curr_expected_line), &label, &contents);
271   }
272 
273   if (line_exists_anywhere(label, contents)) {
274   ¦ cerr << "\nF - " << FUNCTION << "(" << FILE << ":" << LINE << "): line [" << label << ": " << contents << "] out of order in trace:\n";
275   ¦ DUMP("");
276   }
277   else {
278   ¦ cerr << "\nF - " << FUNCTION << "(" << FILE << ":" << LINE << "): missing [" << contents << "] in trace:\n";
279   ¦ DUMP(label);
280   }
281   Passed = false;
282   return false;
283 }
284 
285 void split_label_contents(const string& s, string* label, string* contents) {
286   static const string delim(": ");
287   size_t pos = s.find(delim);
288   if (pos == string::npos) {
289   ¦ *label = "";
290   ¦ *contents = trim(s);
291   }
292   else {
293   ¦ *label = trim(s.substr(0, pos));
294   ¦ *contents = trim(s.substr(pos+SIZE(delim)));
295   }
296 }
297 
298 bool line_exists_anywhere(const string& label, const string& contents) {
299   for (vector<trace_line>::iterator p = Trace_stream->past_lines.begin();  p != Trace_stream->past_lines.end();  ++p) {
300   ¦ if (label != p->label) continue;
301   ¦ if (contents == trim(p->contents)) return true;
302   }
303   return false;
304 }
305 
306 int trace_count(string label) {
307   return trace_count(label, "");
308 }
309 
310 int trace_count(string label, string line) {
311   if (!Trace_stream) return 0;
312   long result = 0;
313   for (vector<trace_line>::iterator p = Trace_stream->past_lines.begin();  p != Trace_stream->past_lines.end();  ++p) {
314   ¦ if (label == p->label) {
315   ¦ ¦ if (line == "" || trim(line) == trim(p->contents))
316   ¦ ¦ ¦ ++result;
317   ¦ }
318   }
319   return result;
320 }
321 
322 int trace_count_prefix(string label, string prefix) {
323   if (!Trace_stream) return 0;
324   long result = 0;
325   for (vector<trace_line>::iterator p = Trace_stream->past_lines.begin();  p != Trace_stream->past_lines.end();  ++p) {
326   ¦ if (label == p->label) {
327   ¦ ¦ if (starts_with(trim(p->contents), trim(prefix)))
328   ¦ ¦ ¦ ++result;
329   ¦ }
330   }
331   return result;
332 }
333 
334 bool trace_doesnt_contain(string label, string line) {
335   return trace_count(label, line) == 0;
336 }
337 
338 bool trace_doesnt_contain(string expected) {
339   vector<string> tmp = split_first(expected, ": ");
340   return trace_doesnt_contain(tmp.at(0), tmp.at(1));
341 }
342 
343 vector<string> split(string s, string delim) {
344   vector<string> result;
345   size_t begin=0, end=s.find(delim);
346   while (true) {
347   ¦ if (end == string::npos) {
348   ¦ ¦ result.push_back(string(s, begin, string::npos));
349   ¦ ¦ break;
350   ¦ }
351   ¦ result.push_back(string(s, begin, end-begin));
352   ¦ begin = end+SIZE(delim);
353   ¦ end = s.find(delim, begin);
354   }
355   return result;
356 }
357 
358 vector<string> split_first(string s, string delim) {
359   vector<string> result;
360   size_t end=s.find(delim);
361   result.push_back(string(s, 0, end));
362   if (end != string::npos)
363   ¦ result.push_back(string(s, end+SIZE(delim), string::npos));
364   return result;
365 }
366 
367 string trim(const string& s) {
368   string::const_iterator first = s.begin();
369   while (first != s.end() && isspace(*first))
370   ¦ ++first;
371   if (first == s.end()) return "";
372 
373   string::const_iterator last = --s.end();
374   while (last != s.begin() && isspace(*last))
375   ¦ --last;
376   ++last;
377   return string(first, last);
378 }
379 
380 :(before "End Includes")
381 #include <vector>
382 using std::vector;
383 #include <list>
384 using std::list;
385 #include <map>
386 using std::map;
387 #include <set>
388 using std::set;
389 
390 #include <sstream>
391 using std::istringstream;
392 using std::ostringstream;
393 
394 #include <fstream>
395 using std::ifstream;
396 using std::ofstream;
397 
398 #include "termbox/termbox.h"
399 
400 :(before "End Globals")
401 //: In future layers we'll use the depth field as follows:
402 //:
403 //: Errors will be depth 0.
404 //: Mu 'applications' will be able to use depths 1-100 as they like.
405 //: Primitive statements will occupy 101-9989
406 extern const int Initial_callstack_depth = 101;
407 extern const int Max_callstack_depth = 9989;
408 //: Finally, details of primitive Mu statements will occupy depth 9990-9999
409 //: (more on that later as well)
410 //:
411 //: This framework should help us hide some details at each level, mixing
412 //: static ideas like layers with the dynamic notion of call-stack depth.