### 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 reduce information spilling between them. #### Automate the Testing of JSL Using Hamcrest Have you written some JSL and gotten tired of manually testing after every change? Have you inadvertently broken some piece of your application, or has the fear of doing so prevented you from making the changes you want to make? 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 can be specialized for your needs. In fact, JMP development even uses them to test JMP itself. #### Documentation Check out our [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. #### Basic Usage JSL-Hamcrest has several different pieces that you can choose to use for testing. You can use most of these separately or you can combine them. These 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 all of this. The most common scenario is a combination of test cases and assertions like: ```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 a `Setup` and `Teardown` expression 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 you can focus on the test itself. The `ut assert that` is how you write an actual assertion. The first argument (the test expression) should always be wrapped in `Expr` so we 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 which give informative descriptions and failures. You can use `ut assert that` outside of `ut test` if you want. Mock functions can be used to test callbacks. These look like: ```jsl Data Table List Subscription Test = ut test case("Data Table List Subscription") <. 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 a lot 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 )]^" ) ); ); ``` With 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 Please visit the [GitHub](https://github.com/sassoftware/jsl-hamcrest) for more details on implementation, usage, and contributions. #### Attributions Icons 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/)

Marketplace

Language

Create

Publish

JSL-Hamcrest

Overview

Reviews

Q&A