Merge pull request #184 from tSQLt-org/github-pages

GitHub pages pulling latest from github-pages branch

Author: lizbaron

.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# These owners will be the default owners for everything in
+# the repo. Unless a later match takes precedence,
+# @global-owner1 and @global-owner2 will be requested for
+# review when someone opens a pull request.
+* @tsqlt-org/maintainers

docs/_config.yml

@@ -1,3 +1,9 @@
 theme: jekyll-theme-dinky
 title: tSQLt - Database Unit Testing for SQL Server
-description: tSQLt is the open source framework for unit testing on SQL Server
+description: tSQLt is the open source framework for unit testing on SQL Server
+defaults:
+  -
+    scope:
+      path: ""
+    values:
+      layout: "default"

docs/index.md

@@ -1,5 +1,3 @@
 ---
-layout: default
 ---
-
 WELCOME TO TSQLT, THE OPEN SOURCE DATABASE UNIT TESTING FRAMEWORK FOR SQL SERVER

docs/user-guide/assertions/assertemptytable.md

@@ -0,0 +1,58 @@
+# AssertEmptyTable
+
+## Syntax
+
+``` sql
+tSQLt.AssertEmptyTable [@TableName = ] 'name of table to be checked' [, [@Message = ] 'message' ]
+```
+
+## Arguments
+
+[**@TableName** = ] name of table to be checked
+
+The name of a table which is expected to be empty. @Expected is NVARCHAR(MAX) with no default.
+
+[**@Message** = ] ‘message’
+
+Optional. String containing an additional failure message to be used if the expected and actual values are not equal. @Message is NVARCHAR(MAX) with a default of ‘unexpected/missing resultset rows!’.
+
+## Return Code Values
+
+Returns 0
+
+## Errors Raised
+
+Raises a `failure` error if the table contains any rows.
+
+## Result Sets
+None
+
+## Overview
+
+AssertEmptyTable checks if a table is empty. If the table does contain any rows, the failure message displays all rows found.
+
+## Examples
+
+Example: AssertEqualsTable to check the results of a view
+This test case uses AssertEqualsTable to compare the data returned by a view to an expected data set.
+
+``` sql
+CREATE PROCEDURE testFinancialApp.[test that Report generates no rows if base tables are empty]
+AS
+BEGIN
+    IF OBJECT_ID('actual') IS NOT NULL DROP TABLE actual;
+
+------Fake Table
+    EXEC tSQLt.FakeTable 'FinancialApp', 'CurrencyConversion';
+    EXEC tSQLt.FakeTable 'FinancialApp', 'Sales';
+
+------Execution
+    SELECT amount, currency, customerId, employeeId, itemId, date
+      INTO actual
+      FROM FinancialApp.Report('USD');
+
+------Assertion
+    EXEC tSQLt.AssertEmptyTable 'actual';
+END;
+GO
+```

docs/user-guide/assertions/assertequals.md

@@ -0,0 +1,93 @@
+# AssertEquals
+
+## Syntax
+
+``` sql
+tSQLt.AssertEquals [@expected = ] expected value, [@actual = ] actual value[, [@message = ] 'message' ]
+```
+
+## Arguments
+[**@Expected** = ] expected value
+
+The expected value for the test. @Expected is SQL_VARIANT with no default.
+
+[**@Actual** = ] actual value
+
+The actual value resulting from processing during the test. @Actual is SQL_VARIANT with no default.
+
+[**@Message** = ] ‘message’
+
+Optional. String containing an additional failure message to be used if the expected and actual values are not equal. @Message is NVARCHAR(MAX) with no default.
+
+## Return Code Values
+Returns 0
+
+## Error Raised
+Raises a `failure` error if expected and actual are not equal.
+
+Raises an `Operand type clash` error if the value passed for @Expected or @Actual is not compatible with SQL_VARIANT. The most common form of this is VARCHAR(MAX) – for this `tSQLt.AssertEqualsString` is provided.
+
+## Result Sets
+None
+
+## Overview
+`tSQLt.AssertEquals` compares two values for equality. If they are not equal, the test case is failed; otherwise, `tSQLt.AssertEquals` does not affect test processing. For the purposes of `tSQLt.AssertEquals`, NULL is considered equal to NULL. Any non-NULL value is considered not equal to NULL.
+
+## Examples
+### Example: `tSQLt.AssertEquals` to check the results of a function
+This test case uses `tSQLt.AssertEquals` to compare the return result of a function with an expected value.
+
+``` sql
+CREATE PROCEDURE testFinancialApp.[test that ConvertCurrencyUsingLookup converts using conversion rate in CurrencyConversion table]
+AS
+BEGIN
+    DECLARE @expected MONEY; SET @expected = 3.2;
+    DECLARE @actual MONEY;
+    DECLARE @amount MONEY; SET @amount = 2.00;
+    DECLARE @sourceCurrency CHAR(3); SET @sourceCurrency = 'EUR';
+    DECLARE @destCurrency CHAR(3); SET @destCurrency = 'USD';
+
+------Fake Table
+    EXEC tSQLt.FakeTable 'FinancialApp', 'CurrencyConversion';
+
+    INSERT INTO FinancialApp.CurrencyConversion (id, SourceCurrency, DestCurrency, ConversionRate)
+                                         VALUES (1, @sourceCurrency, @destCurrency, 1.6);
+------Execution
+    SELECT @actual = amount FROM FinancialApp.ConvertCurrencyUsingLookup(@sourceCurrency, @destCurrency, @amount);
+
+------Assertion
+    EXEC tSQLt.assertEquals @expected, @actual;
+END;
+GO
+```
+
+### Example: A variety of the possibilities of `tSQLt.AssertEquals`
+
+The examples below show what to expect from AssertEquals when called with different values.
+
+``` sql
+    EXEC tSQLt.AssertEquals 12345.6789, 12345.6789; -- pass
+    EXEC tSQLt.AssertEquals 'hello', 'hello'; -- pass
+    EXEC tSQLt.AssertEquals N'hello', N'hello'; -- pass
+
+    DECLARE @datetime DATETIME; SET @datetime = CAST('12-13-2005' AS DATETIME);
+    EXEC tSQLt.AssertEquals @datetime, @datetime; -- pass
+
+    DECLARE @bit BIT; SET @bit = CAST(1 AS BIT);
+    EXEC tSQLt.AssertEquals @bit, @bit; -- pass
+
+    EXEC tSQLt.AssertEquals NULL, NULL; -- pass
+    EXEC tSQLt.AssertEquals 17, NULL; -- fail
+    EXEC tSQLt.AssertEquals NULL, 17; -- fail
+
+    EXEC tSQLt.AssertEquals 12345.6789, 54321.123; -- fail
+    EXEC tSQLt.AssertEquals 'hello', 'goodbye'; -- fail
+
+    DECLARE @datetime1 DATETIME; SET @datetime1 = CAST('12-13-2005' AS DATETIME);
+    DECLARE @datetime2 DATETIME; SET @datetime2 = CAST('07-19-2005' AS DATETIME);
+    EXEC tSQLt.AssertEquals @datetime1, @datetime2; -- fail
+
+    DECLARE @bit1 BIT; SET @bit1 = CAST(1 AS BIT);
+    DECLARE @bit2 BIT; SET @bit2 = CAST(1 AS BIT);
+    EXEC tSQLt.AssertEquals @bit1, @bit2; -- pass
+```

docs/user-guide/assertions/assertequalsstring.md

@@ -0,0 +1,65 @@
+# AssertEqualsString
+
+## Syntax
+
+``` sql
+tSQLt.AssertEqualsString [@expected = ] expected value
+                       , [@actual = ] actual value
+                      [, [@message = ] 'message' ]
+```
+
+## Arguments
+[**@Expected** = ] expected value
+
+The expected value for the test. @Expected is NVARCHAR(MAX) with no default.
+
+[**@Actual** = ] actual value
+
+The actual value resulting from processing during the test. @Actual is NVARCHAR(MAX) with no default.
+
+[**@Message** = ] ‘message’
+
+Optional. String containing an additional failure message to be used if the expected and actual values are not equal. @Message is NVARCHAR(MAX) with no default.
+
+## Return Code Values
+Returns 0
+
+## Error Raised
+Raises a `failure` error if expected and actual are not equal.
+
+## Result Sets
+None
+
+## Overview
+`tSQLt.AssertEqualsString` compares two string values for equality. If they are not equal, the test case is failed; otherwise, `tSQLt.AssertEqualsString` does not affect test processing. For the purposes of `tSQLt.AssertEqualsString`, NULL is considered equal to NULL. Any non-NULL value is considered not equal to NULL.
+
+## Examples
+### Example: AssertEqualsString to check the results of a function
+This test case uses AssertEqualsString to compare the return result of a function with an expected value. The function formats a first and last name into a standard string for display.
+
+``` sql
+CREATE PROC TestPerson.[test FormatName concatenates names correctly]
+AS
+BEGIN
+    DECLARE @expected NVARCHAR(MAX); SET @expected = 'Smith, John';
+    DECLARE @actual NVARCHAR(MAX);
+
+    SELECT @actual = person.FormatName('John', 'Smith');
+
+    EXEC tSQLt.AssertEqualsString @expected, @actual;
+END;
+```
+
+### Example: A variety of the possibilities of AssertEqualsString
+
+The examples below show what to expect from AssertEqualsString when called with different values.
+
+``` sql
+EXEC tSQLt.AssertEqualsString 'hello', 'hello'; -- pass
+EXEC tSQLt.AssertEqualsString N'goodbye', N'goodbye'; -- pass
+EXEC tSQLt.AssertEqualsString 'hello', N'hello'; - pass (values are compared as NVARCHAR(MAX)
+
+EXEC tSQLt.AssertEqualsString 'hello', NULL; -- fail
+EXEC tSQLt.AssertEqualsString NULL, 'hello'; -- fail
+EXEC tSQLt.AssertEqualsString NULL, NULL; -- pass
+```

docs/user-guide/assertions/assertequalstable.md

@@ -0,0 +1,117 @@
+# AssertEqualsTable
+
+## Syntax
+
+``` sql
+tSQLt.AssertEqualsTable [@Expected = ] 'expected table name'
+                      , [@Actual = ] 'actual table name'
+                     [, [@FailMsg = ] 'message' ]
+```
+
+## Arguments
+[**@Expected** = ] expected table name
+
+The name of a table which contains the expected results for the test. @Expected is NVARCHAR(MAX) with no default.
+
+[**@Actual** = ] actual table name
+
+The name of a table which contains the results from processing during the test. @Actual is NVARCHAR(MAX) with no default.
+
+[**@FailMsg** = ] ‘message’
+
+Optional. String containing an additional failure message to be used if the expected and actual values are not equal. @FailMsg is NVARCHAR(MAX) with a default of ‘unexpected/missing resultset rows!’.
+
+## Return Code Values
+Returns 0
+
+## Errors Raised
+Raises a `failure` error if the contents of the expected table and the actual table are not equal.
+
+Certain datatypes cannot be compared with `tSQLt.AssertEqualsTable`. If the tables being compared contain an unsupported datatype, the following error will be raised:
+
+ > The table contains a datatype that is not supported for `tSQLt.AssertEqualsTable`.
+
+The following datatypes are known to be unsupported by `tSQLt.AssertEqualsTable`: text, ntext, image, xml, geography, geometry, rowversion and CLR datatypes that are not marked comparable and byte ordered.
+
+## Result Sets
+None
+
+## Overvoew
+`tSQLt.AssertEqualsTable` compares the contents of two tables for equality. It does this by comparing each row of the tables for an exact match on all columns. If the tables do not contain the same data, the failure message displays which rows could not be matched.
+
+## Examples
+### Example: AssertEqualsTable to check the results of a view
+This test case uses AssertEqualsTable to compare the data returned by a view to an expected data set.
+
+``` sql
+CREATE PROCEDURE testFinancialApp.[test that Report gets sales data with converted currency]
+AS
+BEGIN
+    IF OBJECT_ID('actual') IS NOT NULL DROP TABLE actual;
+    IF OBJECT_ID('expected') IS NOT NULL DROP TABLE expected;
+
+------Fake Table
+    EXEC tSQLt.FakeTable 'FinancialApp', 'CurrencyConversion';
+    EXEC tSQLt.FakeTable 'FinancialApp', 'Sales';
+
+    INSERT INTO FinancialApp.CurrencyConversion (id, SourceCurrency, DestCurrency, ConversionRate)
+                                         VALUES (1, 'EUR', 'USD', 1.6);
+    INSERT INTO FinancialApp.CurrencyConversion (id, SourceCurrency, DestCurrency, ConversionRate)
+                                         VALUES (2, 'GBP', 'USD', 1.2);
+
+    INSERT INTO FinancialApp.Sales (id, amount, currency, customerId, employeeId, itemId, date)
+                                         VALUES (1, '1050.00', 'GBP', 1000, 7, 34, '1/1/2007');
+    INSERT INTO FinancialApp.Sales (id, amount, currency, customerId, employeeId, itemId, date)
+                                         VALUES (2, '4500.00', 'EUR', 2000, 19, 24, '1/1/2008');
+
+------Execution
+    SELECT amount, currency, customerId, employeeId, itemId, date
+      INTO actual
+      FROM FinancialApp.Report('USD');
+
+------Assertion
+    CREATE TABLE expected (
+	    amount MONEY,
+	    currency CHAR(3),
+	    customerId INT,
+	    employeeId INT,
+	    itemId INT,
+	    date DATETIME
+    );
+
+	INSERT INTO expected (amount, currency, customerId, employeeId, itemId, date) SELECT 1260.00, 'USD', 1000, 7, 34, '2007-01-01';
+	INSERT INTO expected (amount, currency, customerId, employeeId, itemId, date) SELECT 7200.00, 'USD', 2000, 19, 24, '2008-01-01';
+
+	EXEC tSQLt.AssertEqualsTable 'expected', 'actual';
+END;
+GO
+```
+
+## Understanding The Output
+When the two tables being compared contain different data, the results are displayed as a text table in the failure message. The first column of this text table (\_m\_) describes the result of the comparison. The symbol “<” indicates that the row was found in the Expected table but did not match anything in the Actual table. The symbol “>” indicates that the row was found in the Actual table but not in the Expected table. Finally, the symbol “=” indicates that the row was matched between the Expected and Actual tables.
+
+For example, consider the following Expected and Actual tables:
+
+Expected
+|col1|col2|col3|
+|---|---|---|
+|1|A|a|
+|2|B|b|
+|3|C|c|
+
+Actual
+|col1|col2|col3|
+|---|---|---|
+|1|A|a|
+|3|X|c|
+
+These tables would result in the following failure message:
+
+
+`failed: unexpected/missing resultset rows!`
+|_m_|col1|col2|col3|
+|---|---|---|---|
+|<  |2   |B   |b   |
+|<  |3   |C   |c   |
+|=  |1   |A   |a   |
+|>  |3   |X   |c   |