### Overview This add-in is an implementation of [Hamcrest](http://hamcrest.org/) for JSL. It provides a framework for writing expressive tests with informative failure messages. This framework allows tests to be more self-contained and minimizes information spilling between them. #### Automate the Testing of JSL by Using Hamcrest Have you written some JSL and tired of manually testing after every change? Have you inadvertently broken a part of your application, or has the fear of doing so prevented you from making the changes that you want? With automated testing, you can be more confident in your changes. Now available is a set of tools for automating the testing of JSL. This framework includes the creation of tests and test cases, as well as an implementation of the well-known Hamcrest assertion library. Hamcrest provides flexible ways to assert what you know to be true about the behavior of your JSL. These tools are full-featured, and you can customize them for your needs. In fact, JMP development even uses them to test JMP itself. #### Documentation Explore the [documentation](https://sassoftware.github.io/jsl-hamcrest/#File:Matchers-Index.txt) website for detailed information about using JSL-Hamcrest. ### How to Use #### Installing Open the `JSL-Hamcrest.jmpaddin` file in JMP to install the add-in. #### Basic Usage JSL-Hamcrest has different components that you can use for your tests. You can use most of these components separately, or you can combine them. The components include assertions (`ut assert that` and matchers), test cases (`ut test`, `ut test case`), mock functions (`ut mock function`), and the reporter (`ut global reporter`) that underlies everything. The most common scenario is a combination of test cases and assertions, such as: ```jsl formulas test case = ut test case("Formulas") << Setup(Expr( dt = Open("$SAMPLE_DATA Big Class.jmp"); )) << Teardown(Expr( Close(dt, NoSave); // Unnecessary )) << Skip If(Expr(Day Of Week(Today()) == 4), "It's Wednesday"); ut test(formulas test case, "Advance Row", Expr( dt << new column("Test", Formula(Row())); ut assert that(Expr(dt:Test << Get Values), (1::40)`); )); ut test(formulas test case, "Char", Expr( dt << new column("Test", Formula(Char(Row()))); ut assert that(Expr(dt:Test << Get Values), ut starts with({"1", "2", "3"})); )); ut test("Big Class", "Row Count", Expr( dt = Open("$SAMPLE_DATA Big Class.jmp"); ut assert that(Expr(N Rows(dt)), ut greater than(38), "large"); )); ``` The `ut test case` allows `Setup` and `Teardown` expressions that are run before and after *each* `ut test`. The `ut test` also ensures that all windows, tables, errors, and symbols get cleaned up so that you can focus on the test itself. The `ut assert that` is how you write an actual assertion. You should always wrap the first argument (the test expression) in `Expr` so that you can test errors and report better test failures. The second argument (the expected) can be a value or a `matcher` like `ut starts with`. These are declarative descriptions of what you would like to test and provide informative descriptions and failures. You can also use `ut assert that` outside of `ut test`. You can use mock functions to test callbacks. These functions look like: ```jsl Data Table List Subscription Test = ut test case("Data Table List Subscription") << Setup(Expr( mock open = ut mock function({dt}, Expr("open"; .)); sub name = Subscribe to Data Table List(, OnOpen( Function({dt}, mock open:fn(dt)) ) ); )) << Teardown(Expr( Unsubscribe to Data Table List(sub name, "ALL"); ut verify mock(mock open); )); ut test(Data Table List Subscription Test, "OnOpen/OnClose called for Open", Expr( ut expect call(mock open, { ut name( ut host table name( "Big Class" ) ) } ); Open( "$SAMPLE_DATA/Big Class.jmp" ); )); ``` `ut mock function` defines an instrumented function that you can use as a callback. `ut expect call` adds expectations about how many times that function will be called and with what arguments. And `ut verify mock` makes sure that the expectations are met. Finally, there are reporters. Usually, you do not need to worry about the reporter because it is handled automatically by the add-in when initialized or when a test runner GUI is added to a script editor. However, if you want to do something else, you need to know how to use a reporter. There can be only *one* reporter, `ut global reporter`, and it determines what happens when test successes, failures, and so on are reported from `ut mock function`, `ut assert that`, `ut test`, and so on. Here are examples that show reporters and how to use them: ```jsl // Does nothing ut global reporter = ut reporter(); ut assert that(Expr(1 + 1), 3); ``` ```jsl // Writes to the log as successes, failures, etc come in ut global reporter = ut streaming log reporter with skip(); ut assert that(Expr(1 + 1), 3); ``` ```jsl // Collects into a buffer until you show the report explicitly ut global reporter = ut collecting reporter(); ut assert that(Expr(1 + 1), 3); ut global reporter << show report(); ``` ```jsl // Saves test results as rows in a JMP data table ut global reporter = ut data table reporter(); ut test("Addition", "Addition works", Expr( ut assert that(Expr(1 + 1), 3, "woops") ) ); ut global reporter << New Data View; ``` Again, typically, you do not need to worry about setting `ut global reporter` explicitly because the add-in handles it for you. #### Using the Hamcrest Test-Runner Add-In 1. Install the add-in. 2. Write tests in a JMP script editor. 3. Attach a Test-Runner to the editor. 4. Press the play icon. #### Writing a New Matcher The ability to create new matchers is part of what makes JSL-Hamcrest so powerful. You can create matchers for your own specific use case or contribute one back to the community. #### UtMatcher Class The first step is to define a class that has `UtMatcher` as its base class. You only need to define the `_init_` (if needed), `matches`, and `describe` methods within your class. ```jsl /* Class: UtDayOfWeekMatcher Checks the day of week for a date. */ Define Class( "UtDayOfWeekMatcher", Base Class( "UtMatcher" ), value = .; days = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"}; // Method: _init_ // Needed if value or inner matcher needs to be saved _init_ = Method( {value}, this:value = value; ); // Method: matches // Return match info with success/failure info matches = Method( {test expr}, // This evaluates the test expression actual = test expr; // Dates are numbers in JMP, so check the type first // Name Expr() is needed to prevent actual from // evaluating again in case it is an expression. If( !Is Number( Name Expr( actual ) ), // This returns the match info ut match info failure( Eval Insert( "^Name Expr( actual )^ was of type ^Type( Name Expr( actual ) )^" ) ), // If matches the correct day of week, return success Day of Week( actual ) == this:value, ut match info success(), // else not on given day of week, return failure ut match info failure( Eval Insert( "^As Date( actual )^ was on ^this:days[Day of Week( actual )]^" ) ) ); ); // Method: describe // Describes the be expected outcome describe = Method( {}, Eval Insert( "date falling on a ^this:days[Day of Week( this:value )]^" ) ); ); ``` #### Matcher Factory After you define the matcher, you must create a factory function. This function's name is what is used in assertions. Include a call to `ut matcher factory` to register the matcher that is needed for some other matchers. ```jsl /* Function: ut day of week Factory function for . Example: ---JSL--- d = 01aug2019; ut assert that( Expr( d ), ut day of week( 5 ) ); --------- */ ut matcher factory( "ut day of week", Expr(Function( {val}, // Do necessary type checking of input variables // in factory function. If( !Is Number( val ), Throw( "ut day of week() requires a numeric date value as the argument" ), ); New Object( UtDayOfWeekMatcher( Name Expr( val ) ) ); )), "ut day of week( value )", //Prototype "Matches based on the day of the week of a given date value." // Description ); ``` #### UtTypedMatcher You can also derive from `UtTypedMatcher` to have any type checking done for you. This simplifies much of what happens in the `matches` method. ```jsl Define Class( "UtDayOfWeekMatcher", Base Class( "UtTypedMatcher" ), value = .; days = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"}; allowable types = {Date, Number}; _init_ = Method( {value}, this:value = value; ); // Method: typed matches // Handle a pre-evaluated and typed checked actual value. typed matches = Method( {actual}, day = Day of Week( actual ); If( day == this:value, ut match info success(), // else ut match info failure( Eval Insert( "^As Date( actual )^ was on ^this:days[Day of Week( actual )]^" ) ) ); ); describe = Method( {}, Eval Insert( "date falling on a ^this:days[Day of Week( this:value )]^" ) ); ); ``` When deriving from `UtTypedMatcher`, you are required to inject a self-reference onto the matcher within the factory function. ```jsl ut day of week = Function( {val}, If( !Is Number( val ), Throw( "ut day of week() requires a numeric date value as the argument" ), ); ut new object( "UtDayOfWeekMatcher", Eval List( {Name Expr( val )} ) ); ); ``` #### Multiple Factories You can have multiple factory functions for a single matcher to either change the comparison method (like less than/greater than) or to improve the wording, such as `ut on thursday()` instead of `ut day of week( 5 )`. ```jsl ut on thursday = Function( {}, ut day of week( 5 ); ); ``` ### Additional Details Visit the [GitHub](https://github.com/sassoftware/jsl-hamcrest) repository for more details on implementation, usage, and contributions. #### Attributions Icons that are used in the JSL-Hamcrest add-in were adapted from the [Material Design Icons](https://github.com/google/material-design-icons) by Google under their [Apache 2.0 License](https://github.com/google/material-design-icons/blob/master/LICENSE). #### Additional Resources * Original presentation materials from JMP Discovery Summit Europe 2019 can be found [here](https://community.jmp.com/t5/Discovery-Summit-Europe-2019/Automate-the-Testing-of-JSL-Using-Hamcrest-2019-EU-45MP-061/ta-p/110062). * [Hamcrest.org](http://hamcrest.org/)

Language

FAQ

Publish

JSL-Hamcrest

Overview

Reviews

Q&A