diff --git a/README.md b/README.md index d4985a4..372e9e7 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,19 @@ -Excel-TDD: Excel Testing Library -================================ +VBA-TDD +======= -Bring the reliability of other programming realms to Excel with Test-Driven Development for Excel. +Bring the reliability of other programming realms to VBA with Test-Driven Development (TDD) for VBA on Windows and Mac. Quick example: -```VB.net -Sub Specs() - On Error Resume Next +```vb +Function Specs() As SpecSuite + Set Specs = New SpecSuite + Specs.Description = "Add" - ' Create a new collection of specs - Dim Specs As New SpecSuite + ' Report results to the Immediate Window + ' (ctrl + g or View > Immediate Window) + Dim Reporter As New ImmediateReporter + Reporter.ListenTo Specs ' Describe the desired behavior With Specs.It("should add two numbers") @@ -24,8 +27,6 @@ Sub Specs() .Expect(Add(1, 2, 3)).ToEqual 6 .Expect(Add(1, 2, 3, 4)).ToEqual 10 End With - - InlineRunner.RunSuite Specs End Sub Public Function Add(ParamArray Values() As Variant) As Double @@ -37,68 +38,31 @@ Public Function Add(ParamArray Values() As Variant) As Double Next i End Function -' Open the Immediate Window (Ctrl+g or View > Immediate Window) and Run Specs (F5)' -' = PASS (2 of 2 passed) ========================== +' Immediate Window: +' +' === Add === +' + should add two numbers +' + should add any number of numbers +' = PASS (2 of 2 passed) = ``` -For details of the process of reaching this example, see the [TDD Example](https://github.com/timhall/Excel-TDD/wiki/TDD-Example) +For details of the process of reaching this example, see the [TDD Example](https://github.com/VBA-tools/VBA-TDD/wiki/TDD-Example) ### Advanced Example -For an advanced example of what is possible with Excel-TDD, check out the [specs for Excel-REST](https://github.com/timhall/Excel-REST/tree/master/specs) - -Methods used in these specs: - -- Using `BeforeEach` to reset before each spec is run -- Testing VBA modules and classes -- Setting up a custom `DisplayRunner` and `InlineRunner` -- Waiting for and handling async behavior +For an advanced example of what is possible with VBA-TDD, check out the [specs for VBA-Web](https://github.com/VBA-tools/VBA-Web/tree/master/specs) ### Getting Started -For testing macros: - -- The lightweight Inline Runner is recommended and should be added directly to the workbook that is being tested -- Add `InlineRunner.bas`, `SpecDefinition.cls`, `SpecExpectation.cls`, and `SpecSuite.cls` to your workbook -- If starting from scratch, the `Excel-TDD - Blank - Inline.xlsm` workbook includes all of the required classes and modules - -For testing workbooks: - -- The full Workbook Runner is recommended in order to keep testing behavior separate from the workbook that is being tested -- Use the `Excel-TDD - Blank.xlsm` workbook -- See the [Workbook Runner Example](https://github.com/timhall/Excel-TDD/wiki/Workbook-Runner-Example) for details - -### Inline Runner - -The inline runner is a lightweight test runner that is intended to be loaded directly into the workbook that is being tested and is for testing macros and simple behaviors in the workbook -All results are displayed in the Immediate Window (Ctrl+g or View > Immediate Window) and the runner requires no setup to run test suites - -```VB.net -InlineRunner.RunSuite Specs - -' = PASS (2 of 2 passed) ========================== - -' Configurable -InlineRunner.RunSuite Specs, ShowFailureDetails:=True, ShowPassed:=True, ShowSuiteDetails:=True - -' = PASS (2 of 2 passed) ========================== -' + 2 specs -' + should add two numbers -' + should add any number of numbers -' === -``` - -### Workbook Runner - -The workbook runner is a full test runner that is intended to be used separately of the workbook that is being tested to keep testing behavior separate. -It is for testing advanced workbook behaviors and allows for reseting the test workbook between tests, using scenarios for tests (see below), and running tests against different test workbooks. -See the [Workbook Runner Example](https://github.com/timhall/Excel-TDD/wiki/Workbook-Runner-Example) for details +1. Download the [latest release (v2.0.0-beta)](https://github.com/VBA-tools/VBA-TDD/releases) +2. Add `src/SpecSuite.cls`, `src/SpecDefinition.cls`, `src/SpecExpectation.cls`, add `src/ImmediateReporter.cls` to your project +3. If you're starting from scratch with Excel, you can use `VBA-TDD - Blank.xlsm` ### It and Expect `It` is how you describe desired behavior and once a collection of specs is written, it should read like a list of requirements. -```VB.net +```vb With Specs.It("should allow user to continue if they are authorized and up-to-date") ' ... End With @@ -110,7 +74,7 @@ End With `Expect` is how you test desired behavior -```VB.net +```vb With Specs.It("should check values") .Expect(2 + 2).ToEqual 4 .Expect(2 + 2).ToNotEqual 5 @@ -155,7 +119,59 @@ With Specs.It("should test complex things") End With ``` -For more details, check out the [Wiki](https://github.com/timhall/Excel-TDD/wiki) +### ImmediateReporter + +With your specs defined, the easiest way to display the test results is with `ImmediateReporter`. This outputs results to the Immediate Window (`ctrl+g` or View > Immediate Window) and is useful for running your tests without leaving the VBA editor. + +```vb +Public Function Specs As SpecSuite + Set Specs = New SpecSuite + Specs.Description = "..." + + ' Create reporter and attach it to these specs + Dim Reporter As New ImmediateReporter + Reporter.ListenTo Specs + + ' -> Reporter will now output results as they are generated +End Function +``` + +### RunMatcher + +For VBA applications that support `Application.Run` (which is at least Windows Excel, Word, and Access), you can create custom expect functions with `RunMatcher`. + +```vb +Public Function Specs As SpecSuite + Set Specs = New SpecSuite + + With Specs.It("should be within 1 and 100") + .Expect(50).RunMatcher "ToBeWithin", "to be within", 1, 100 + ' ^ Actual + ' ^ Public Function to call + ' ^ message for matcher + ' ^ 0+ Args to pass to matcher + End With +End Function + +Public Function ToBeWithin(Actual As Variant, Args As Variant) As Variant + If UBound(Args) - LBound(Args) < 1 Then + ' Return string for specific failure message + ToBeWithin = "Need to pass in upper-bound to ToBeWithin" + Else + If Actual >= Args(0) And Actual <= Args(1) Then + ' Return true for pass + ToBeWithin = True + Else + ' Return false for fail or custom failure message + ToBeWithin = False + End If + End If +End Function +``` + +To avoid compilation issues on unsupported applications, the compiler constant `EnableRunMatcher` in `SpecExpectation.cls` should be set to `False`. + +For more details, check out the [Wiki](https://github.com/VBA-tools/VBA-TDD/wiki) - Design based heavily on the [Jasmine](http://pivotal.github.com/jasmine/) - Author: Tim Hall diff --git a/Excel-TDD - Blank.xlsm b/VBA-TDD - Blank.xlsm similarity index 100% rename from Excel-TDD - Blank.xlsm rename to VBA-TDD - Blank.xlsm diff --git a/specs/Excel-TDD - Specs.xlsm b/specs/Excel-TDD - Specs.xlsm deleted file mode 100644 index dc745c1..0000000 Binary files a/specs/Excel-TDD - Specs.xlsm and /dev/null differ diff --git a/specs/VBA-TDD - Specs.xlsm b/specs/VBA-TDD - Specs.xlsm new file mode 100644 index 0000000..7bd0609 Binary files /dev/null and b/specs/VBA-TDD - Specs.xlsm differ diff --git a/src/ImmediateReporter.cls b/src/ImmediateReporter.cls index 3a61ff3..45a7100 100644 --- a/src/ImmediateReporter.cls +++ b/src/ImmediateReporter.cls @@ -9,7 +9,7 @@ Attribute VB_PredeclaredId = False Attribute VB_Exposed = True '' ' ImmediateReporter v2.0.0-beta -' (c) Tim Hall - https://github.com/VBA-tools/Excel-TDD +' (c) Tim Hall - https://github.com/VBA-tools/VBA-TDD ' ' Report results to Immediate Window ' diff --git a/src/SpecDefinition.cls b/src/SpecDefinition.cls index f446508..d26ebc8 100644 --- a/src/SpecDefinition.cls +++ b/src/SpecDefinition.cls @@ -9,7 +9,7 @@ Attribute VB_PredeclaredId = False Attribute VB_Exposed = True '' ' SpecDefinition v2.0.0-beta -' (c) Tim Hall - https://github.com/VBA-tools/Excel-TDD +' (c) Tim Hall - https://github.com/VBA-tools/VBA-TDD ' ' Collection of expectations for verifying spec ' diff --git a/src/SpecExpectation.cls b/src/SpecExpectation.cls index 2bc39a7..72b16d9 100644 --- a/src/SpecExpectation.cls +++ b/src/SpecExpectation.cls @@ -9,7 +9,7 @@ Attribute VB_PredeclaredId = False Attribute VB_Exposed = True '' ' SpecExpectation v2.0.0-beta -' (c) Tim Hall - https://github.com/VBA-tools/Excel-TDD +' (c) Tim Hall - https://github.com/VBA-tools/VBA-TDD ' ' Provides various tests that can be performed for a provided value ' diff --git a/src/SpecSuite.cls b/src/SpecSuite.cls index a27f187..c25135b 100644 --- a/src/SpecSuite.cls +++ b/src/SpecSuite.cls @@ -9,7 +9,7 @@ Attribute VB_PredeclaredId = False Attribute VB_Exposed = True '' ' SpecSuite v2.0.0-beta -' (c) Tim Hall - https://github.com/VBA-tools/Excel-TDD +' (c) Tim Hall - https://github.com/VBA-tools/VBA-TDD ' ' A collection of specs and results ' diff --git a/src/WorkbookReporter.cls b/src/WorkbookReporter.cls index c89bb6c..d11c86d 100644 --- a/src/WorkbookReporter.cls +++ b/src/WorkbookReporter.cls @@ -9,11 +9,14 @@ Attribute VB_PredeclaredId = False Attribute VB_Exposed = True '' ' DisplayReporter v2.0.0-beta -' (c) Tim Hall - https://github.com/VBA-tools/Excel-TDD +' (c) Tim Hall - https://github.com/VBA-tools/VBA-TDD ' ' Report results to Worksheet ' ' @class DisplayReporter +' @compatibility +' Platforms: Windows and Mac +' Applications: Excel-only ' @author tim.hall.engr@gmail.com ' @license MIT (http://www.opensource.org/licenses/mit-license.php) ' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ '