Test coverage for HTML (and documentation revisions)
Nick Reid
Dear dev-
tldr;
Updating HTML coding conventions on confluence here -- want feedback on requirements for unit testing.
Nikodem Graczewski and I have been discussing how to apply unit tests to our HTML templates that are used through out the OpenLMIS-UI.
HTML templates do contain logic and business requirements, so they should be included in our testing
strategy. I feel that Nikodem is right in building these unit tests, but I am worried they are too strict and could cause maintenance/extension issues.
I've done some googling on the issue, and there really isn't great guidance on the issue. HTML is generally viewed as a configuration layer in AngularJS, not a piece of business logic.
This issue could be resolved with an integration testing strategy, but those workflows are harder to maintain than unit tests. Toolsets like PhantomCSS don't really feel like the right direction we should go either.
Questions:
- What tools/strategies have you used in the past that worked well (or not so well)?
- Do these requirements for unit tests on HTML in AngularJS make sense:
- Views display information described in business requirements
- View honor and expose contract from controller
- Dynamic logic works when page state changes
- How can we write these unit tests so they are not tightly coupled to testing the HTML markup -- but test behavior and business requirements
Side note: I started updated the UI Documentation, mainly by breaking up the files so its easily readable and reference able (since us UI folk would refer to our conventions, but be completely wrong about what was written). If group editing these guidelines in confluence works, we will start this with other sections.
You can see the documentation changes here:
http://docs.openlmis.org/en/latest/conventions/index.html#
Nick Reid | nick...@villagereach.org
Software Developer, Information Systems Group
VillageReach Starting
at the Last Mile
2900 Eastlake Ave. E, Suite 230, Seattle, WA 98102, USA
CELL: +1.510.410.0020
SKYPE: nickdotreid
www.villagereach.org
Paweł Gesek
Nick Reid | nick.reid@villagereach.org
Software Developer, Information Systems Group
VillageReach Starting at the Last Mile
2900 Eastlake Ave. E, Suite 230, Seattle, WA 98102, USA
CELL: +1.510.410.0020
SKYPE: nickdotreid
www.villagereach.org
--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/CY4PR02MB21995C347DE6189CC95426B094660%40CY4PR02MB2199.namprd02.prod.outlook.com.
For more options, visit https://groups.google.com/d/optout.
--
Paweł Gesek
Technical Project Manager
pge...@soldevelo.com / +48 690 020 875
SolDevelo Sp. z o.o. [LLC] / www.soldevelo.com
Al. Zwycięstwa 96/98, 81-451, Gdynia, Poland
Phone: +48 58 782 45 40 / Fax: +48 58 782 45 41
Nick Reid
The more I've researched and talked to people about this — no one seems to seriously do this — and I agree, some of these tests really are a place where selenium testing would/could/should be done. The reason we are having this conversation seems to come out of the discussions we had this summer about regressions.
Here is the list the Pawel Gesek mentioned (for those not immersed in the thread)
HTML Unit Testing Requirements
(1) Ensure HTML views display the information described in a ticket
(2) Verify that HTML views connect to the contract exposed by their controller
(3) Dynamic AngularJS elements act as defined when scope variables change
My thoughts is response to Pawel Gasek
(1) Is generally the place where high-level business logic driven integration are written, and I think since our stories are focusing more on vertical slices of functionality — we should be accomplishing this in integration tests
(2) seems
like a unit test of the controller, so its kinda redundant
(3) Checking dynamic HTML changes with selenium would be a pain, and I don't think we want to make integration tests with super deep logic
The example of modals updating values on the page, should really be tested in the controller logic — as the internal logic of the modal should be mocked, and the controller should just be checking that calling the change function updates the correct data element. I'd argue that any piece of HTML that knows about a modal is too broadly scoped.
Nick Reid | nick...@villagereach.org
Software Developer, Information Systems Group
VillageReach Starting
at the Last Mile
2900 Eastlake Ave. E, Suite 230, Seattle, WA 98102, USA
CELL: +1.510.410.0020
SKYPE: nickdotreid
www.villagereach.org
Sent: Tuesday, September 26, 2017 3:03:58 AM
To: Nick Reid
Cc: Openlmis Dev Mailing List
Subject: Re: [openlmis-dev] Test coverage for HTML (and documentation revisions)
Nick Reid
Dear dev-
I felt that I can bring this thread back up, as I've had more time to think about how HTML fits into the OpenLMIS-UI -- and I thought I'd share my thoughts before I start making tickets.
Please reply to the list, or email me directly, if you disagree or have questions. I'm friendly!
tldr; I can't find anyone that thinks unit testing HTML is a good idea. HTML should be treated as a configuration layer.
--> We will test our HTML in end-to-end tests (once we figure out that strategy)
NOTE: This doesn't apply to HTML in components or directives
The HTML we use to define routes/pages is great because it is relatively simple to read and understand how a specific piece of HTML turns into a screen. These types of files are easy for an implementer to replace, if they can pick out atomic pieces they want to replace AND don't have to worry about creating a syntax error (that an HTML linter can't find).
For comparison, our unit tests should follow a DAMP methodology because it allows another developer to understand how a specific section of code works. The reason DAMP works is that unit tests must be simple enough that you don't have to unit test your unit tests (or unit testing library). This is referred to as cyclomatic complexity.
In our HTML, we need to work to keep the cyclomatic complexity low -- which is unfortunately difficult because AngularJS gives us tons of fun methods that makes putting complexity into HTML fast and simple.
Here is what I'm planning to add to our HTML coding conventions:
(A) No "ng-if"
(B) Model driven forms
- Most complex forms we have written represent domain objects, and objects are much easier to test/maintain
- Simple forms should still use HTML attributes
(C) HTML segments/files should represent content, without "wrapper" divits, which will promote reuse and decrease complexity
Please comment and suggest other ways we can reduce the complexity of HTML files
thanks!
--- nick ---
Nick Reid | nick...@villagereach.org
Software Developer, Information Systems Group
VillageReach Starting
at the Last Mile
2900 Eastlake Ave. E, Suite 230, Seattle, WA 98102, USA
CELL: +1.510.410.0020
SKYPE: nickdotreid
www.villagereach.org
Sent: Tuesday, September 26, 2017 8:23:05 AM
To: Paweł Gesek
Nikodem Graczewski
I'm curious about removing ng-ifs from our code base. How would we be achieving the same result? We will have to hide/show some parts of the UI based on a condition eventually.
Best regards,
Nikodem
Dear dev-
I felt that I can bring this thread back up, as I've had more time to think about how HTML fits into the OpenLMIS-UI -- and I thought I'd share my thoughts before I start making tickets.
Please reply to the list, or email me directly, if you disagree or have questions. I'm friendly!
tldr; I can't find anyone that thinks unit testing HTML is a good idea. HTML should be treated as a configuration layer.
--> We will test our HTML in end-to-end tests (once we figure out that strategy)
NOTE: This doesn't apply to HTML in components or directives
The HTML we use to define routes/pages is great because it is relatively simple to read and understand how a specific piece of HTML turns into a screen. These types of files are easy for an implementer to replace, if they can pick out atomic pieces they want to replace AND don't have to worry about creating a syntax error (that an HTML linter can't find).
For comparison, our unit tests should follow a DAMP methodology because it allows another developer to understand how a specific section of code works. The reason DAMP works is that unit tests must be simple enough that you don't have to unit test your unit tests (or unit testing library). This is referred to as cyclomatic complexity.
In our HTML, we need to work to keep the cyclomatic complexity low -- which is unfortunately difficult because AngularJS gives us tons of fun methods that makes putting complexity into HTML fast and simple.
Here is what I'm planning to add to our HTML coding conventions:
(A) No "ng-if"
(B) Model driven forms
- Most complex forms we have written represent domain objects, and objects are much easier to test/maintain
- Simple forms should still use HTML attributes
(C) HTML segments/files should represent content, without "wrapper" divits, which will promote reuse and decrease complexity
Please comment and suggest other ways we can reduce the complexity of HTML files
thanks!
--- nick ---
Nick Reid | nick.reid@villagereach.org
Software Developer, Information Systems Group
VillageReach Starting at the Last Mile
2900 Eastlake Ave. E, Suite 230, Seattle, WA 98102, USA
CELL: +1.510.410.0020
SKYPE: nickdotreid
www.villagereach.org
From: openlm...@googlegroups.com <openlm...@googlegroups.com> on behalf of Nick Reid <nick...@villagereach.org>
Sent: Tuesday, September 26, 2017 8:23:05 AM
To: Paweł Gesek
Cc: Openlmis Dev Mailing List
Subject: Re: [openlmis-dev] Test coverage for HTML (and documentation revisions)
The more I've researched and talked to people about this — no one seems to seriously do this — and I agree, some of these tests really are a place where selenium testing would/could/should be done. The reason we are having this conversation seems to come out of the discussions we had this summer about regressions.
Here is the list the Pawel Gesek mentioned (for those not immersed in the thread)
HTML Unit Testing Requirements
(1) Ensure HTML views display the information described in a ticket
(2) Verify that HTML views connect to the contract exposed by their controller
(3) Dynamic AngularJS elements act as defined when scope variables change
My thoughts is response to Pawel Gasek
(1) Is generally the place where high-level business logic driven integration are written, and I think since our stories are focusing more on vertical slices of functionality — we should be accomplishing this in integration tests
(2) seems like a unit test of the controller, so its kinda redundant
(3) Checking dynamic HTML changes with selenium would be a pain, and I don't think we want to make integration tests with super deep logic
The example of modals updating values on the page, should really be tested in the controller logic — as the internal logic of the modal should be mocked, and the controller should just be checking that calling the change function updates the correct data element. I'd argue that any piece of HTML that knows about a modal is too broadly scoped.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/CY4PR02MB2199AD6A0AE0962A33E79366947B0%40CY4PR02MB2199.namprd02.prod.outlook.com.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/CY4PR02MB2199FAB3CB1BC9B73640E69D94330%40CY4PR02MB2199.namprd02.prod.outlook.com.
Nick Reid
Nikodem~
I'll admit that I put the idea of removing if-statements from HTML templating to make sure people read it -- it's a nutty idea that takes an extremely hard stance that I'm not fully committed to. I've thought about getting rid or ng-repeat (because that is a huge source of performance issues), but am worried about how they would be replaced.
I would like to avoid code that looks like this (which doesn't even include ng-if)
<h2 class="modal-title">{{'cceEditInventoryItem.' + (vm.inventoryItem.id ? 'editEquipmentDetails' :'addNewColdChainEquipment') | message}}</h2>
Source openlmis-cce-ui - src/cce-edit-inventory-item/edit-inventory-item.html
I'd simplify this code by moving it into a controller or router - which will be made easier by separating logic and presentation.
What scares me about evaluated logic in an HTML template is that it is hard to unit test, and can be hard to read. The example above shows logic that could be easily missed by a developer making changes.
Another example of an ng-if statement that worries me is:
<fieldset ng-if="vm.newStatus && !vm.isFunctioning(vm.newStatus)">
Source openlmis-cce-ui - src/cce-inventory-item-status/status-update-modal.html#L47
What I'm concerned about here is that there isn't a specific method we can unit test.
An example that I'm more comfortable is:
<fieldset ng-if="vm.isObsolete(vm.newStatus)">
Source openlmis-cce-ui - src/cce-inventory-item-status/status-update-modal.html#L58
There is a specific method that we can test here. What would make this if statement even better is if either the method didn't take a parameter OR the method checked only one value in an object.
Nikodem - I'd also like to hear about what worries you with how we are expressing this logic in HTML. The CCE-UI is the only place we have a HTML unit testing utility library, so if there are examples there -- I'd like to know your thoughts....
-- nick --
Nick Reid | nick...@villagereach.org
Software Developer, Information Systems Group
VillageReach Starting
at the Last Mile
2900 Eastlake Ave. E, Suite 230, Seattle, WA 98102, USA
CELL: +1.510.410.0020
SKYPE: nickdotreid
www.villagereach.org
Nikodem Graczewski
I totally understand the two ng-if issues you have mentioned, but from my understanding, they are more about our code readability rather than ng-if themselves. I don't think that getting rid of ng-repeat and ng-if is the way to go as we would have to replace them with something, which would most likely lead us to reinventing the wheel. However, I think that simplifying conditions passed to ng-ifs is a valid point and something we should focus on improving. Actually the clearest (and most performant - as we have observed recently) way would be to use a simple flag.
Best regards,
Nikodem
Nikodem~
I'll admit that I put the idea of removing if-statements from HTML templating to make sure people read it -- it's a nutty idea that takes an extremely hard stance that I'm not fully committed to. I've thought about getting rid or ng-repeat (because that is a huge source of performance issues), but am worried about how they would be replaced.
I would like to avoid code that looks like this (which doesn't even include ng-if)
<h2 class="modal-title">{{'cceEditInventoryItem.' + (vm.inventoryItem.id ? 'editEquipmentDetails' :'addNewColdChainEquipment') | message}}</h2>Source openlmis-cce-ui - src/cce-edit-inventory-item/edit-inventory-item.html
I'd simplify this code by moving it into a controller or router - which will be made easier by separating logic and presentation.
What scares me about evaluated logic in an HTML template is that it is hard to unit test, and can be hard to read. The example above shows logic that could be easily missed by a developer making changes.
Another example of an ng-if statement that worries me is:
<fieldset ng-if="vm.newStatus && !vm.isFunctioning(vm.newStatus)">
Source openlmis-cce-ui - src/cce-inventory-item-status/status-update-modal.html#L47
What I'm concerned about here is that there isn't a specific method we can unit test.
An example that I'm more comfortable is:
<fieldset ng-if="vm.isObsolete(vm.newStatus)">
Source openlmis-cce-ui - src/cce-inventory-item-status/status-update-modal.html#L58
There is a specific method that we can test here. What would make this if statement even better is if either the method didn't take a parameter OR the method checked only one value in an object.
Nikodem - I'd also like to hear about what worries you with how we are expressing this logic in HTML. The CCE-UI is the only place we have a HTML unit testing utility library, so if there are examples there -- I'd like to know your thoughts....
-- nick --
Nick Reid
Nikodem, I think we are in agreement.
There will come a time (in the far away future) that we move away from the AngularJS to format our HTML - but that will be a separate discussion, and I don't think there is an obvious choice for that at the moment.
-- nick --
Nick Reid | nick...@villagereach.org
Software Developer, Information Systems Group
VillageReach Starting
at the Last Mile
2900 Eastlake Ave. E, Suite 230, Seattle, WA 98102, USA
CELL: +1.510.410.0020
SKYPE: nickdotreid
www.villagereach.org