From e1655b34ec3c275e281a5e8247a5fdde59641dde Mon Sep 17 00:00:00 2001
From: paranoiq <cz.paranoiq@gmail.com>
Date: Tue, 28 Jun 2022 15:31:25 +0200
Subject: [PATCH] Little bit of doc

---
 doc/doc.md     | 14 ++++++++++----
 doc/testing.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+), 4 deletions(-)
 create mode 100644 doc/testing.md

diff --git a/doc/doc.md b/doc/doc.md
index 6f98154f..72527b9b 100644
--- a/doc/doc.md
+++ b/doc/doc.md
@@ -1,8 +1,14 @@
 
-Random doc:
+Documentation index:
+====================
 
+as all doc, this doc is also not current, but it can give some insight into how things generally work
+
+- [Testing](testing.md)
 - [Parser exceptions](parser-exceptions.md)
-- [SQL model hierarchy](sql-model.md)
-- [SQL commands](sql-commands.md)
-- [SQL expression nodes](sql-expression-nodes.md)
 - [Lexer token types](token-types.md)
+- [SQL: model hierarchy](sql-model.md)
+- [SQL: commands](sql-commands.md)
+- [SQL: other statements](sql-compound-statements.md)
+- [SQL: expression nodes](sql-expression-nodes.md)
+- [Some notes to PHP type-hint usage in the project](types.md)
diff --git a/doc/testing.md b/doc/testing.md
new file mode 100644
index 00000000..fe97d66a
--- /dev/null
+++ b/doc/testing.md
@@ -0,0 +1,48 @@
+
+How SQLFTW is currently tested
+==============================
+
+SQLFTW unit tests
+-----------------
+
+there are unit tests of course. these are written against documentation and do not cover 100% of the features yet.
+
+majority of unit tests check parser in this way:
+- parser tests a given SQL code
+- resulting `Command` is serialized back to string
+- original code and result string is compared and should be equal
+
+there are of course some differences. mainly these three:
+- parser does not track white space, so things like spaces and indentation are normalized
+- (My)SQL uses some aliases like `\N` == `null` or `CHARSET` == `CHARACTER SET`. these are also normalized
+- in some cases there are optional syntax features that are normalized (always removed or always added). e.g. optional `=` in table options etc.
+
+unit tests are not the main source of truth!
+
+see `/tests/Parser`
+
+run `composer t` for unit tests
+
+
+Database unit tests
+-------------------
+
+these are the main source of truth
+
+SQLFTW is currently using the test suites from mysql-server project
+
+these tests are written in Perl, using SQL syntax directly combined with Perl syntax. i am doing my best to strip 
+as much non-SQL syntax as possible while keeping as much SQL syntax as possible. resulting code is then being fed to
+`Parser`. the measure for success for now is, whether parser fails and wheter the resulting `Command`s can be serialized. 
+i am not currently checking if it serializes properly. working on that...
+
+this test is being runned on all ~8000 test files from mysql-server source and in all versions since 8.0.0 to current version.
+more versions will be added later (5.7...)
+
+see `/tests/Mysql`
+
+run `php tests/Mysql/test.php` for Mysql tests
+
+requirements:
+- you will need `https://github.com/mysql/mysql-server` cloned to adjacent directory
+- you will need `https://github.com/paranoiq/dogma-debug` wired in for now