Introduce tests/test_utils/mod.rs and use it consistently

To share helper macros between various tests/* we added a new module
(tests/macros/mod.rs). This made the prologue to be used in tests quite
long and a little weird:
```
#[macro_use]
#[path = "macros/mod.rs"]
mod macros;
use sqlparser::test_utils::*;
```

This simplifies it to:
```
#[macro_use]
mod test_utils;
use test_utils::*;
```
- and switches all existing tests to the new prologue simultaneously...

...while fixing a few other inconsistencies and adding a few comments
about the way `test_utils` work.

Author: nickolay

src/lib.rs

@@ -43,4 +43,5 @@ pub mod tokenizer;
 #[doc(hidden)]
 // This is required to make utilities accessible by both the crate-internal
 // unit-tests and by the integration tests <https://stackoverflow.com/a/44541071/1026>
+// External users are not supposed to rely on this module.
 pub mod test_utils;

src/test_utils.rs

@@ -10,6 +10,12 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// This module contains internal utilities used for testing the library.
+/// While technically public, the library's users are not supposed to rely
+/// on this module, as it will change without notice.
+//
+// Integration tests (i.e. everything under `tests/`) import this
+// via `tests/test_utils/mod.rs`.
 use std::fmt::Debug;
 
 use super::ast::*;

tests/sqlparser_common.rs

@@ -19,14 +19,13 @@
 //! dialect-specific parsing rules).
 
 #[macro_use]
-#[path = "macros/mod.rs"]
-mod macros;
+mod test_utils;
+use test_utils::{all_dialects, expr_from_projection, join, number, only, table};
 
 use matches::assert_matches;
 use sqlparser::ast::*;
 use sqlparser::dialect::keywords::ALL_KEYWORDS;
 use sqlparser::parser::ParserError;
-use sqlparser::test_utils::{all_dialects, expr_from_projection, join, number, only, table};
 
 #[test]
 fn parse_insert_values() {

tests/sqlparser_mssql.rs

@@ -14,9 +14,12 @@
 //! Test SQL syntax specific to Microsoft's T-SQL. The parser based on the
 //! generic dialect is also tested (on the inputs it can handle).
 
+#[macro_use]
+mod test_utils;
+use test_utils::*;
+
 use sqlparser::ast::*;
 use sqlparser::dialect::{GenericDialect, MsSqlDialect};
-use sqlparser::test_utils::*;
 
 #[test]
 fn parse_mssql_identifiers() {

tests/sqlparser_mysql.rs

@@ -11,13 +11,15 @@
 // limitations under the License.
 
 #![warn(clippy::all)]
-
 //! Test SQL syntax specific to MySQL. The parser based on the generic dialect
 //! is also tested (on the inputs it can handle).
 
+#[macro_use]
+mod test_utils;
+use test_utils::*;
+
 use sqlparser::ast::*;
 use sqlparser::dialect::{GenericDialect, MySqlDialect};
-use sqlparser::test_utils::*;
 use sqlparser::tokenizer::Token;
 
 #[test]

tests/sqlparser_postgres.rs

@@ -14,10 +14,13 @@
 //! Test SQL syntax specific to PostgreSQL. The parser based on the
 //! generic dialect is also tested (on the inputs it can handle).
 
+#[macro_use]
+mod test_utils;
+use test_utils::*;
+
 use sqlparser::ast::*;
 use sqlparser::dialect::{GenericDialect, PostgreSqlDialect};
 use sqlparser::parser::ParserError;
-use sqlparser::test_utils::*;
 
 #[test]
 fn parse_create_table_with_defaults() {

tests/sqlparser_regression.rs

@@ -10,6 +10,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#![warn(clippy::all)]
+
 use sqlparser::dialect::GenericDialect;
 use sqlparser::parser::Parser;
 

tests/sqlparser_snowflake.rs

@@ -10,11 +10,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#![warn(clippy::all)]
+//! Test SQL syntax specific to Snowflake. The parser based on the
+//! generic dialect is also tested (on the inputs it can handle).
+
 #[macro_use]
-#[path = "macros/mod.rs"]
-mod macros;
+mod test_utils;
+use test_utils::*;
 
-use sqlparser::test_utils::*;
 use sqlparser::ast::*;
 use sqlparser::dialect::{GenericDialect, SnowflakeDialect};
 use sqlparser::tokenizer::*;

tests/sqlparser_sqlite.rs

@@ -14,9 +14,12 @@
 //! Test SQL syntax specific to SQLite. The parser based on the
 //! generic dialect is also tested (on the inputs it can handle).
 
+#[macro_use]
+mod test_utils;
+use test_utils::*;
+
 use sqlparser::ast::*;
 use sqlparser::dialect::{GenericDialect, SQLiteDialect};
-use sqlparser::test_utils::*;
 use sqlparser::tokenizer::Token;
 
 #[test]

tests/macros/mod.rs renamed to tests/test_utils/mod.rs

@@ -10,6 +10,20 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Re-export everything from `src/test_utils.rs`.
+pub use sqlparser::test_utils::*;
+
+// For the test-only macros we take a different approach of keeping them here
+// rather than in the library crate.
+//
+// This is because we don't need any of them to be shared between the
+// integration tests (i.e. `tests/*`) and the unit tests (i.e. `src/*`),
+// but also because Rust doesn't scope macros to a particular module
+// (and while we export internal helpers as sqlparser::test_utils::<...>,
+// expecting our users to abstain from relying on them, exporting internal
+// macros at the top level, like `sqlparser::nest` was deemed too confusing).
+
+#[macro_export]
 macro_rules! nest {
     ($base:expr $(, $join:expr)*) => {
         TableFactor::NestedJoin(Box::new(TableWithJoins {