Chore: update unit test docs, fix minor github ci/cd bot docs typos (#2327)

* Chore: update unit test docs, fix minor github ci/cd bot docs typos

* First within -> under

* Get rid of comma

* Typo

* PR feedback

* Fixup

Author: georgesittas

docs/concepts/tests.md

@@ -1,18 +1,20 @@
 # Testing
 
-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.
+Testing allows you to protect your project from regression by continuously verifying that 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.
 
 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 within `.yaml` files in the `tests/` folder of your SQLMesh project. Each test within a suite file contains the following attributes:
+Test suites are defined using the YAML format. Each suite is a file whose name must begin with `test`, end in either `.yaml` or `.yml`, and is stored under the `tests/` folder of your SQLMesh project.
+
+Tests within a suite file contain the following attributes:
 
 * The unique name of a test
 * 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:
+* Test inputs, which are defined per upstream model or external table 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:
@@ -21,8 +23,6 @@ Test suites are defined using YAML format within `.yaml` files in the `tests/` f
 * [Optional] The dictionary of values for macro variables that will be set during model testing
     * There are three special macros that can be overridden, `start`, `end`, and `execution_time`. Overriding each will allow you to override the date macros in your SQL queries. For example, setting execution_time: 2022-01-01 -> execution_ds in your queries.
 
-A column may be omitted from a row (either input or output), in which case it will be implicitly added with the value `NULL`. For example, this can be useful when specifying input data for wide tables where some columns may not be required to define a test.
-
 The YAML format is defined as follows:
 
 ```yaml linenums="1"
@@ -47,7 +47,7 @@ The YAML format is defined as follows:
     <macro_variable_name>: <macro_variable_value>
 ```
 
-Note: the `rows` key is optional in the above format, so the following would also be valid:
+The `rows` key is optional in the above format, so the following would also be valid:
 
 ```
 <unique_test_name>:
@@ -58,6 +58,26 @@ Note: the `rows` key is optional in the above format, so the following would als
 ...
 ```
 
+### Omitting Columns
+
+Defining the complete inputs and outputs for wide tables, i.e. tables with many columns, can become cumbersome. Therefore, if certain columns can be safely ignored they may be omitted from any row and their value will be treated as `NULL` for that row.
+
+Additionally, it's possible to test only a subset of the output columns by setting `partial` to `true` for the rows of interest:
+
+```yaml linenums="1"
+  ...
+  outputs:
+    query:
+      partial: true
+      rows:
+        - <column_name>: <column_value>
+          ...
+```
+
+This is useful when we can't treat the missing columns as `NULL`, but still want to ignore them.
+
+When `partial` is set, the rows need to be defined as a mapping under the `rows` key and the tested columns are only those that are referenced in them.
+
 ### Example
 
 In this example, we'll use the `sqlmesh_example.full_model` model, which is provided as part of the `sqlmesh init` command and defined as follows:
@@ -108,9 +128,9 @@ test_example_full_model:
         num_orders: 1
 ```
 
-Note that `ds` is redundant in the above test, since it is not referenced in `full_model`, so it may be omitted.
+The `ds` column is not needed in the above test, since it is not referenced in `full_model`, so it may be omitted.
 
-Let's also assume that we are only interested in testing the `num_orders` output column, i.e. we only care about the `id` input column of `sqlmesh_example.incremental_model`. Then, we could rewrite the above test more compactly as follows:
+If we were only interested in testing the `num_orders` column, we could only specify input values for the `id` column of `sqlmesh_example.incremental_model`, thus rewriting the above test more compactly as follows:
 
 ```yaml linenums="1"
 test_example_full_model:
@@ -127,7 +147,7 @@ test_example_full_model:
       - num_orders: 3
 ```
 
-Leaving out the input column `item_id` means that it will be implicitly added in all input rows with a `NULL` value. Thus, we expect the corresponding output column to only contain `NULL` values, which is indeed reflected in the above test since the `item_id` column is also omitted from `query`'s rows.
+Since [omitted columns](#omitting-columns) are treated as `NULL`, this test also implicitly asserts that both the input and the output `item_id` columns are `NULL`, which is correct.
 
 ### Testing CTEs
 
@@ -185,11 +205,13 @@ test_example_full_model:
 
 ## Automatic test generation
 
-Creating tests manually is a cumbersome and, ironically, error-prone process, especially as the number of rows and columns of the involved models grows. To address this, SQLMesh provides the [`create_test` command](../reference/cli.md#create_test), which can be used to automatically create tests for a given model.
+Creating tests manually can be repetitive and error-prone, which is why SQLMesh also provides a way to automate this process using the [`create_test` command](../reference/cli.md#create_test).
+
+This command can generate a complete test for a given model, as long as the tables of the upstream models it references exist in the project's data warehouse and are already populated with data.
 
 ### Example
 
-Since we already have a test for `sqlmesh_example.full_model`, in this example we'll show how to generate a test for `sqlmesh_example.incremental_model`, which is provided as part of the `sqlmesh init` command and defined as follows:
+In this example, we'll show how to generate a test for `sqlmesh_example.incremental_model`, which is another model provided as part of the `sqlmesh init` command and defined as follows:
 
 ```sql linenums="1"
 MODEL (
@@ -213,34 +235,35 @@ WHERE
 
 ```
 
-As one may expect, we need to start by specifying what the input data are for `sqlmesh_example.seed_model`. The `create_test` command achieves this by executing a user-supplied query against the target warehouse of the SQLMesh project to produce the input rows of the aforementioned model.
+Firstly, we need to specify the input data for the upstream model `sqlmesh_example.seed_model`. The `create_test` command starts by executing a user-supplied query against the project's data warehouse and uses the returned data to produce the test's input rows.
 
-Let's assume that we're only interested in specifying three input rows for `sqlmesh_example.seed_model`. One way to do that is by executing the following query:
+For instance, the following query will return three rows from the table corresponding to the model `sqlmesh_example.seed_model`:
 
 ```sql linenums="1"
 SELECT * FROM sqlmesh_example.seed_model LIMIT 3
 ```
 
-However, notice that `sqlmesh_example.incremental_model` also contains a filter which references the `@start_ds` and `@end_ds` [macro variables](macros/macro_variables.md). To ensure that the produced test will always pass, we modify the above query to constrain the value range of the `ds` column:
+Next, notice that `sqlmesh_example.incremental_model` contains a filter which references the `@start_ds` and `@end_ds` [macro variables](macros/macro_variables.md).
+
+To make the generated test deterministic and thus ensure that it will always succeed, we need to define these variables and modify the above query to constrain `ds` accordingly.
+
+If we set `@start_ds` to `'2020-01-01'` and `@end_ds` to `'2020-01-04'`, the above query needs to be changed to:
 
 ```sql linenums="1"
--- The dates '2020-01-01' and '2020-01-04' have been picked arbitrarily
 SELECT * FROM sqlmesh_example.seed_model WHERE ds BETWEEN '2020-01-01' AND '2020-01-04' LIMIT 3
 ```
 
-We will also define these variables in the test, so that the filter of `sqlmesh_example.incremental_model` matches that range after it's been rendered.
+Finally, combining this query with the proper macro variable definitions, we can compute the expected output for the model's query in order to generate the complete test.
 
-Finally, we don't have to specify the output `query` attribute, since we can compute its values given the input data produced by the above query.
-
-The following command captures all of the above:
+This can be achieved using the following command:
 
 ```bash
 $ sqlmesh create_test sqlmesh_example.incremental_model --query sqlmesh_example.seed_model "select * from sqlmesh_example.seed_model where ds between '2020-01-01' and '2020-01-04' limit 3" --var start '2020-01-01' --var end '2020-01-04'
 ```
 
-Running this command produces the following new test, which is located at `tests/test_incremental_model.yaml`:
+Running this creates the following new test, located at `tests/test_incremental_model.yaml`:
 
-```yaml linenums="1" hl_lines="16-22"
+```yaml linenums="1"
 test_incremental_model:
   model: sqlmesh_example.incremental_model
   inputs:
@@ -270,7 +293,7 @@ test_incremental_model:
     end: '2020-01-04'
 ```
 
-As shown below, we now have two passing tests:
+As shown below, we now have two passing tests. Hooray!
 
 ```bash
 $ sqlmesh test
@@ -281,8 +304,6 @@ Ran 2 tests in 0.024s
 OK
 ```
 
-Note: since the `sqlmesh create_test` command executes queries directly in the target warehouse, the tables of the involved models must be built first, otherwise the queries will fail.
-
 ## Running tests
 
 ### Automatic testing with plan
@@ -292,6 +313,7 @@ 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
 .
@@ -321,18 +343,18 @@ Ran 1 test in 0.012s
 FAILED (failures=1)
 ```
 
-Note: when there are many differing columns, the corresponding DataFrame will be truncated by default, but it can be fully rendered using the `-v` option (verbose) of the `sqlmesh test` command.
+Note: when there are many differing columns, the corresponding DataFrame will be truncated by default, but it can be fully displayed using the `-v` (verbose) option of the `sqlmesh test` command.
 
 ### 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_full_model.yaml::test_example_full_model
+```bash
+$ sqlmesh test tests/test_full_model.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_*
+```bash
+$ sqlmesh test tests/test_*
 ```

docs/integrations/github.md

@@ -213,8 +213,7 @@ on:
     - created
 ```
 
-Note: `issue_comment` event will not work until this change in merged to your main branch. 
-Therefore to enable this you will need to make the change in a branch, merge, and then future branches will support the deploy command. 
+Note: the `issue_comment` event will not work until this change is merged into your main branch. Therefore, to enable this you will need to make the change in a branch, merge, and then future branches will support the deploy command.
 
 ### Desynchronized Production Code and Data Configuration