Planner 1142 blog for unit tests in xlsx files #109
Conversation
| @@ -0,0 +1,122 @@ | |||
| = Unit tests in .xlsx files | |||
There was a problem hiding this comment.
The title must catch your attention like a newspaper headline. The title is not the time to be complete or comprehensive.
What is the main benefit of this article to readers? I'd say: to allow business people to compose and validate unit tests.
Proposals for the title:
A) Let the business users write the JUnit tests in Excel or LibreOffice
B) Unit testing constraints with business input from Excel/LibreOffice
The adoc file name needs to be adjusted accordingly.
| :awestruct-layout: blogPostBase | ||
| :awestruct-tags: [useCase] | ||
|
|
||
| After you implement a planning problem, you must write unit tests for every score rule. |
There was a problem hiding this comment.
The first paragraph of the blog is considered "the abstract". It's copy-pasted on summary pages such as
https://www.optaplanner.org/blog/ and in the google search results (it directly affects Click Through Rate)
Ideally, that first paragraph is 3-4 sentences long and explains why someone should take the time to read this article. It's far more important than the rest of the article (except the title), because:
- if the title is boring, people won't click on the link
- if the first paragraph is talking about something useful to them, people won't read the article
So, let's change this into something like:
"The business experts explain the business constraints to us, the developers. But how can we be sure that we understood them correctly? Or worse, how can we test that they agree among themselves once the constraints are formalized?
Well, there's one great way to do that: JUnit tests populated by XLS data. We allow them to recreate a small subset of the solution in Excel/LibreOffice and let them decide how many constraints match. Then our JUnit tests test if our constraint implementations adhere to those requirements."
|
|
||
| == Traditional unit tests | ||
|
|
||
| In Conference Scheduling example, if you want to test room conflict constraint (hard penalty per pair of talks in the same room in overlapping timeslots) |
There was a problem hiding this comment.
Try to favor using active voice, see https://developers.google.com/style/voice
So instead of "... if you want to test room ..." simply "... to test room ...".
Instead of you "... you might write something like this:", simply "... write:"
- Shorter sentences that have the same information are better. (less is more)
- Show confidence and authority. Otherwise you're sending subliminal messages to the reader that he/she shouldn't waste his/her time reading this. Do be humble when it comes down to claiming things like "the best" etc without scientific proof.
|
|
||
|
|
||
| == Unit tests in .xlsx files | ||
| In order to avoid initializing unwanted fields, you can take advantage of https://github.com/kiegroup/optaplanner/blob/master/optaplanner-examples/src/main/java/org/optaplanner/examples/conferencescheduling/persistence/ConferenceSchedulingXlsxFileIO.java[ConferenceSchedulingXlsxFileIO] |
|
|
||
|
|
||
| == Conclusion | ||
| To test your score rules in an xlsx file, follow these steps: |
There was a problem hiding this comment.
put xlsx between ` ticks
That way it becomes xlsx styled
| // talks in same room with overlapping time slots | ||
| talk2.withTimeslot(slot2); | ||
| scoreVerifier.assertHardWeight(ROOM_CONFLICT, -10, solution); | ||
| } |
There was a problem hiding this comment.
This test is long. It doesn't need to be complete, it just needs to be complete enough to serve as a "BEFORE" example, to compare with the "AFTER" case.
Can we shorten it or replace parts with "..." to make it less verbose?
| 3. List only the fields that you want to use for the corresponding rule. | ||
| 4. Set _testFileName_ in https://github.com/kiegroup/optaplanner/blob/master/optaplanner-examples/src/main/test/java/org/optaplanner/examples/conferencescheduling/solver/ConferenceSchedulingScoreRulesXlsxTest.java[ConferenceSchedulingScoreRulesXlsxTest] and run the test file. | ||
|
|
||
| The test file clones a separate solution instance for every test sheet, so the assigned planning variables in one sheet will not affect |
There was a problem hiding this comment.
that's an implementation detail. Those don't belong in the conclusion.
An Introduction should specify the problem, incite people to read the article
A conclusion should reiterate and summarize the solution, the gain the benefit.
No description provided.