Incorporating comments, adding outputs, editing. (#438)

Author: technically-tracy

docs/concepts/models/overview.md

@@ -95,38 +95,7 @@ MODEL (
 ```
 
 ## Macros
-Macros can be used for passing in paramaterized arguments such as dates, as well as for making SQL less repetitive. By default, SQLMesh provides several predefined macro variables that can be used. Macros are used by prefixing with the `@` symbol.
-
-- @start_date
-```sql
--- The inclusive start interval of an execution casted to a DATETIME SQL object.
-@start_date = CAST("2020-01-01 00:00:00.0" AS DATETIME)
-```
-- @end_date
-```sql
--- The inclusive end interval of an execution casted to a DATETIME SQL object.
-@end_date = CAST("2020-01-01 23:59:59.999000" AS DATETIME)
-```
-- @latest_date
-```sql
--- The latest datetime or current run date of an execution. Used when you only care about the latest data.
-@latest_date = CAST("2020-01-01 00:00:00.0" AS DATETIME)
-```
-- @start_ds
-```sql
--- The inclusive start date string.
-@start_ds = '2020-01-01'
-```
-- @end_ds
-```sql
--- The inclusive end date string.
-@end_ds = '2020-01-01'
-```
-- @latest_ds
-```sql
--- The date string of the run date.
-@end_ds = '2020-01-01'
-```
+Macros can be used for passing in paramaterized arguments such as dates, as well as for making SQL less repetitive. By default, SQLMesh provides several predefined macro variables that can be used. Macros are used by prefixing with the `@` symbol. For more information, refer to [macros](../../concepts/macros.md).
 
 ## Statements
 Models can have additional statements that run before the main query. This can be useful for loading things such as  [UDFs](https://en.wikipedia.org/wiki/User-defined_function). In general, statements should only be used for preparing the main query. They should not be used for creating or altering tables, as this could lead to unpredictable behavior.
@@ -144,30 +113,7 @@ FROM y
 ```
 
 ## Time column
-Models that are loaded incrementally require a time column to partition data. A time column is a column in a model with an optional format string in the dialect of the model; for example, `'%Y-%m-%d'` for DuckDB or `'yyyy-mm-dd'` for Snowflake.
-
-```sql linenums="1"
--- Orders are partitioned by the ds column
-MODEL (
-  name sushi.orders,
-  dialect duckdb,
-  kind INCREMENTAL_BY_TIME_RANGE (
-    time_column (ds, '%Y-%m-%d')
-  )
-);
-
-SELECT
-  id::INT AS id, -- Primary key
-  customer_id::INT AS customer_id, -- Id of customer who made the order
-  waiter_id::INT AS waiter_id, -- Id of waiter who took the order
-  start_ts::TEXT AS start_ts, -- Start timestamp
-  end_ts::TEXT AS end_ts, -- End timestamp
-  ds::TEXT AS ds -- Date of order
-FROM raw.orders
-WHERE
-  ds BETWEEN @start_ds AND @end_ds
-```
-When SQLMesh incrementally inserts data for a partition, it will overwrite any existing data in that partition. For engines that support partitions, it will use an `INSERT OVERWRITE` query. For engines that do not, it will first delete the data in the partition before inserting.
+Models that are loaded incrementally require a time column to partition data. A time column is a column in a model with an optional format string in the dialect of the model; for example, `'%Y-%m-%d'` for DuckDB or `'yyyy-mm-dd'` for Snowflake. For more information, refer to [time column](../../concepts/models/model_kinds.md#time-column).
 
 ### Format string configuration
 The format string tells SQLMesh how your dates are formatted in order to compare start and end dates correctly. You can configure a project-wide default format in your project configuration. A time column format string declared in a model will override the project-wide default. If the model uses a different dialect than the rest of your project, the format string will be automatically transpiled to the model dialect with SQLGlot. SQLMesh will use

docs/concepts/tests.md

@@ -1,24 +1,27 @@
 # Testing
-Testing is how you can protect your project from regression by continuously verifying that the output of each model matches the expectations. Unlike [audits](audits.md), tests are executed either on demand (eg. as part of a CI / CD job) or every time a new [plan](plans.md) is created.
 
-Similarly to unit testing in software development, SQLMesh evaluates the model's logic against predefined inputs and compares the output to expected outcomes provided as part of each test.
+Testing allows you to protect your project from regression by continuously verifying the output of each model matches your expectations. Unlike [audits](audits.md), tests are executed either on demand (for example, as part of a CI/CD job) or every time a new [plan](plans.md) is created.
 
-A comprehensive suite of tests can empower data practitioners to work with confidence, since it allows them to make sure that models behave as expected after changes have been applied to them.
+Similar to unit testing in software development, SQLMesh evaluates the model's logic against predefined inputs and then compares the output to expected outcomes provided as part of each test.
+
+A comprehensive suite of tests can empower data practitioners to work with confidence, as it allows them to ensure models behave as expected after changes have been applied to them.
 
 ## Creating tests
-Test suites are defined using YAML format in files with the `.yaml` extension as part of the `tests/` folder of your SQLMesh project. Each test within a suite file consists of the following attributes:
+
+Test suites are defined using YAML format within `.yaml` files in the `tests/` folder of your SQLMesh project. Each test within a suite file contains the following attributes:
 
 * The unique name of a test
-* The name of the model that is targeted by this test
-* Test inputs. Inputs are defined per external table or upstream model referenced by the target model. Each test input consists of the following:
+* The name of the model targeted by this test
+* Test inputs, which are defined per external table or upstream model referenced by the target model. Each test input consists of the following:
     * The name of an upstream model or external table
     * The list of rows defined as a mapping from a column name to a value associated with it
-* Expected outputs which are defined as follows:
+* Expected outputs, which are defined as follows:
     * The list of rows that are expected to be returned by the model's query defined as a mapping from a column name to a value associated with it
-    * [Optional] The list of expected rows per each individual [Common Table Expression](glossary.md#cte) (CTE) defined in the model's query.
-* [Optional] The dictionary of values for macro variables that will be set during model testing.
+    * [Optional] The list of expected rows per each individual [Common Table Expression](glossary.md#cte) (CTE) defined in the model's query
+* [Optional] The dictionary of values for macro variables that will be set during model testing
 
 The YAML format is defined as follows:
+
 ```yaml linenums="1"
 <unique_test_name>:
   model: <target_model_name>
@@ -38,9 +41,10 @@ The YAML format is defined as follows:
     <macro_variable_name>: <macro_variable_value>
 ```
 
-## Example
+### Example
+
+In this example, we'll use the `sqlmesh_example.example_full_model` model, which is provided as part of the `sqlmesh init` command and defined as follows:
 
-In this example we'll use the `sqlmesh_example.example_full_model` model which is provided as part of the `sqlmesh init` command and is defined as follows:
 ```sql linenums="1"
 MODEL (
   name sqlmesh_example.example_full_model,
@@ -56,9 +60,10 @@ FROM
 GROUP BY item_id
 ```
 
-Notice how the query of the model definition above references one upstream model - `sqlmesh_example.example_incremental_model`.
+Notice how the query of the model definition above references one upstream model: `sqlmesh_example.example_incremental_model`.
 
 The test definition for this model may look like following:
+
 ```yaml linenums="1"
 test_example_full_model:
   model: sqlmesh_example.example_full_model
@@ -85,7 +90,8 @@ test_example_full_model:
 
 ### Testing CTEs
 
-As mentioned previously, individual CTEs within the model's query can also be tested. In this example let's slightly modify the query of the model used in the previous example:
+Individual CTEs within the model's query can also be tested. Let's slightly modify the query of the model used in the previous example:
+
 ```sql linenums="1"
 WITH filtered_orders_cte AS (
     SELECT
@@ -104,7 +110,8 @@ FROM
 GROUP BY item_id
 ```
 
-Below is the example of a test which verifies individual rows returned by the `filtered_orders_cte` CTE before aggregation takes place:
+Below is the example of a test that verifies individual rows returned by the `filtered_orders_cte` CTE before aggregation takes place:
+
 ```yaml linenums="1" hl_lines="16-22"
 test_example_full_model:
   model: sqlmesh_example.example_full_model
@@ -135,10 +142,14 @@ test_example_full_model:
 ```
 
 ## Running tests
-Tests run automatically every time a new [plan](plans.md) is created. Additionally tests can be run on demand using the `sqlmesh test` command.
 
-### The CLI test command
-You can execute tests using the `sqlmesh test` command as follows:
+### Automatic testing with plan
+
+Tests run automatically every time a new [plan](plans.md) is created.
+
+### Manual testing with the CLI
+
+You can execute tests on demand using the `sqlmesh test` command as follows:
 ```bash
 $ sqlmesh test
 .
@@ -148,7 +159,8 @@ Ran 1 test in 0.005s
 OK
 ```
 
-The command returns a non-zero exit code if on any failures and reports them in the standard error stream:
+The command returns a non-zero exit code if there are any failures, and reports them in the standard error stream:
+
 ```bash
 $ sqlmesh test
 F
@@ -169,12 +181,15 @@ Ran 1 test in 0.008s
 FAILED (failures=1)
 ```
 
+### Testing for specific models
 To run a specific model test, pass in the suite file name followed by `::` and the name of the test:
+
 ```
 sqlmesh test tests/test_suite.yaml::test_example_full_model
 ```
 
 You can also run tests that match a pattern or substring using a glob pathname expansion syntax:
+
 ```
 sqlmesh test tests/test_*
 ```

docs/guides/testing.md

@@ -1,36 +1,46 @@
 # Testing guide
-
 ## Testing changes to models
-
 To run unit tests for your models, run the `sqlmesh test` command as follows:
 
 ```bash
 $ sqlmesh test
 .
 ----------------------------------------------------------------------
-Ran 1 test in 0.052s
+Ran 1 test in 0.042s
 
 OK
 ```
-
 As the unit tests run, SQLMesh will identify any that fail.
 
 For more information about tests, refer to [testing](../concepts/tests.md).
 
 ### Test changes to a specific model
 
-To run a specific model test, pass in the module followed by `::` and the name of the test. 
-
-For example: `example_full_model::test_example_full_model.`
+To run a specific model test, pass in the suite file name followed by `::` and the name of the test; for example: `sqlmesh test tests/test_suite.yaml::test_example_full_model`.
 
 ### Run a subset of tests
 
-To run a test that matches a pattern or substring, use the following syntax: `project.tests.test_order*`. 
+To run a test that matches a pattern or substring, use the following syntax: `sqlmesh test tests/test_example*`. 
 
-For example, this will match the following tests: `project.tests.test_orders`, `project.tests.test_order_items`.
+Running the above command will run our `test_example_full_model` test that we ran earlier using `sqlmesh test`:
 
-## Auditing changes to models
+```
+$ sqlmesh test tests/test_example*
+.
+----------------------------------------------------------------------
+Ran 1 test in 0.042s
 
+OK
+```
+
+As another example, running the `sqlmesh test tests/test_order*` command would run the following tests:
+
+* `test_orders`
+* `test_orders_takeout`
+* `test_order_items`
+* `test_order_type`
+
+## Auditing changes to models
 To audit your models, run the `sqlmesh audit` command as follows:
 
 ```bash
@@ -41,7 +51,6 @@ assert_positive_order_ids PASS.
 Finished with 0 audit error(s).
 Done.
 ```
-
 **Note:** Ensure that you have already planned and applied your changes before running an audit.
 
 By default, SQLMesh will halt the pipeline when an audit fails in order to prevent potentially invalid data from propagating further downstream. This behavior can be changed for individual audits by defining them as [non-blocking](../concepts/audits.md#non-blocking-audits).