Annotation names and conventions for persistence extension
dan.j.allen Nov 29, 2011 6:51 PMFirst, great work on the Arquillian persistence extension Bartosz. That has been a much requested feature, so I'm glad it's now in the family.
The point of this post is the open a discussion about the annotation names and convensions. I'll start with the annotation names.
Currently, a data set is specified using an annotation named @Data. That annotation name just doesn't speak to me...unless I knew the gist of the extension (assume I'm a developer just diving into the test suite), I wouldn't be sure what data refers to.
Here are some alternate suggestions.
- @DataSet - Speaks to the fact that this isn't just general data, but a set of data to be used by the test in some way; this also matches the named used by the unitils project
- @LoadDataSet - Here, we actually have an action that indicates the data set is being loaded into the appropriate place for the test
- @UsingDataSet - This reads even nicer when combined with @Test ("test using data set")
- @WithDataSet - Similar to the previous one, though just reads a bit different ("test with data set")
Clearly, I like the term data set better than data. Is there is a reason for sticking with the more general term data? If so, then consider my options without the "Set" part.
The same would go for the @Expected annotation. It should be more clear what is expected. I sort of like @ExpectResultSet. In all, that would read something like:
@Test @UsingDataSet @ExpectResultSet
Or even
@Test @UsingDataSet @ShouldMatchResultSet
The goal here is that you see the test method annotations and in a second you could tell someone what it is likely doing. The annotations also become easier to remember.
Now, let me address a minor convention. I noticed that in all the examples, you are putting the data set files in a directory called "datasets". I like the convention. Why not support it natively? That way, your declaration would simplify from:
@UsingDataSet("datasets/employees.yml")
to:
@UsingDataSet("employees.yml")
(If "datasets" is not a folder, then you could look in the root).
You could even go one step further and allow the extension to be optional, defaulting to YAML...but that might make it too cryptic.
Conventions are cool and they promote a best practice. I recommend that we embrace them.