Annotation names and conventions for persistence extension

[dan.j.allen]

First, 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.

[bmajsak]

Hi Dan,

thanks a lot for sharing your thoughts about persistence extension. This is kind of a feedback I've been waiting for!

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")

You are absolutely right! I'm not particularly happy with current names, because they are not really giving you, as a developer, a full context of the test which you are going to run. But to be honest I wasn't really keen to use the same names as Unitils does However I really like @Using and @With proposal so I would opt for one of them (in favor of @Using).

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.

I would prefer @ExpectResultSet in this case.

Additionally verifying database state at the end of the test could actually come in two flavors:

• strict mode - database should be exactly the same content in the given schema as in provided dataset(s)
• "nice mode" - checking if database contains entries defined in the dataset(s)

We can either introduce a parameter for the @Expect(..) annotation to define the mode (with "nice" as default), or @VerificationMode(TYPE) or even provide different verification annotations for different modes. Currently we are using strict mode based on DBUnit assertion Assertion.assertEqualsIgnoreCols

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.

This convention might be actually quite handy (and reminds me that I really need to put documentation to the confluence soon! ). I will assume /datasets as the default location and if it's not there I will lookup in the root folder.

Actually Persistence Extension already has following convention in place:

• If data set file is not specified it's assumed to be [fully-qualified-class-name]#[testMethodName].[defined-format]. By default format is flat xml data set used by DBUnit, but you can define any other supported as default in arq.xml

With regards to file extension as optional it might make the test more blurry. What if you have two files with the same name and different extension? I know it's not really a good idea but it might happen. Then you need to define which takes precedence (meaning additional entry in arq.xml or sth like that) - which is even more cryptic / hidden I would rather stick to having extension in @DataSet definitions.

Again, thanks a lot for your insight Dan! Much appreciated.

Cheers,

Bartosz

[aslak]

just as a note, the 'Should' notation is in use in Arquillain Container, @Deployment @ShouldThrowException(T)

@Test @RunAsClient @OperatesOnDeployment('X')

@Deployment @TargetsContainer('X') @OverProtocol('X')

@Deployment @TargetsContainer('X') @ShouldThrowException('T')