https://github.com/sassoftware/jsl-hamcrest
Implementation of Hamcrest for JSL.
https://github.com/sassoftware/jsl-hamcrest
hamcrest jmp jsl
Last synced: 2 months ago
JSON representation
Implementation of Hamcrest for JSL.
- Host: GitHub
- URL: https://github.com/sassoftware/jsl-hamcrest
- Owner: sassoftware
- License: apache-2.0
- Created: 2019-09-26T17:33:21.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-02-06T19:27:57.000Z (over 2 years ago)
- Last Synced: 2025-02-13T13:24:47.432Z (4 months ago)
- Topics: hamcrest, jmp, jsl
- Homepage:
- Size: 1.68 MB
- Stars: 11
- Watchers: 9
- Forks: 8
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# JSL-Hamcrest
Implementation of Hamcrest (hamcrest.org) for JSL. Write expressive tests with
informative failure messages. Make tests more self-contained and reduce
information spilling between them.
## Abstract - JMP Discovery Summit 2019
### 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. The
presentation will cover this framework and its use in testing an example JSL
application, from individual functions to the automation of GUI interactions.
## Documentation
Check out our [documentation](https://sassoftware.github.io/jsl-hamcrest/#File:Matchers-Index.txt) website for detailed information about using JSL-Hamcrest.
## Getting Started
### System Requirements
* Works on Mac and Windows operating systems
* Requires JMP 14.1 or higher
### 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 );
);
```
## Building Documentation
1. Download [Natural Docs](naturaldocs.org)
2. Navigate to the root of this project
3. Run NaturalDocs
> NaturalDocs Docs
4. Open `Docs/_html/index.html`
## Releasing a Version
See [Semantic Versioning](semver.org) for details on version numbers.
1. Check `CHANGELOG.md`, `addin.def`, and `Source/DevAddin/addin.def` for correct (current) version number.
2. Build the documentation and remove `Working Data` folder.
3. Zip up the entire repository with `addin.def` at the root (don't include the `.git` or `.github` folder).
4. Rename the zip file as `JSL-Hamcrest-v...jmpaddin`.
5. Zip up the `Source/DevAddin` folder with its `addin.def` at the root.
6. Rename the zip file as `JSL-Hamcrest-Dev-v...jmpaddin`.
7. Push a tag of the form `v..`.
8. Create a GitHub release. Add the relevant `CHANGELOG` section there and attach the two addins.
9. Update the `gh-pages` branch
10. Create a new Pull Request bumping the version number to the next predicted (see files from (1))
## Support
We use GitHub for tracking bugs and feature requests. Please submit a GitHub issue or pull request for support.
## Contributing
We welcome your contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to submit contributions to this project.
## License
This project is licensed under the [Apache 2.0 License](LICENSE).
## 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/)