Ruby 2.6 introduces `Enumerable#filter` as an alias to
`Enumerable#select`, and so our Filterable.filter method will not work
with Ruby 2.6.
So we're renaming the method to `filter_by`, which is similar to
`find_by`. We could also change the `filter` method so if a block is
given it delegates to `Enumerable#filter`, the same way ActiveRecord
handles the `select` method, but IMHO this is easier to follow.
Now we can use the checkbox label text directly as locator at spec,
also default web_sections are created before every spec by loading
`db/seeds.rb` file so we were duplicating "Proposals" WebSection.
We were allowing users to check/uncheck the "Visible to valuators"
checkbox even when the budget is finished and so the investments cannot
be edited. So users were still able to check/uncheck this attribute, but
the server was silently rejecting these changes.
We've considered removing the column in this case but decided to keep it
since users can already control which columns they'd like to display.
We added the background role to the production and preproduction
environments in commit d0b0782c4, but forgot to add it to the staging
environment as well.
There are a dozen ways to add an icon used for decoration. Each of them
offers advantages and disadvantages regarding these topics:
* Accessibility
* Ease of use for developers
* Ease of customization for CONSUL installations
* Maintainability
* Resulting file size
* Number of HTTP requests
* Browser support
* Robustness
We were using one of the most common ones: icon fonts. This technique
shines in many of these aspects. However, it misses the most important
one: accessibility. Users who configure their browser to display a
custom font would see "missing character" icons where our icons should
be displayed. Some users have pointed out they use a custom font because
they're dyslexic and webs using icon fonts make it extremely painful for
them [1].
Screen reader users might also be affected, since screen readers might
try to read the UTF-8 character used by the icon (even if it uses a UTF
Private Use Area) and will react to it in inconsistent ways. Since right
now browser support for different techniques to prevent it with CSS
ranges from non-existant (CSS speech module) to limited (use an
alternative text in the `content` property [2]), we've been adding an
HTML element with an `aria-hidden` attribute. However, by doing so the
ease of customizations for CONSUL installations is reduced, since
customizing ERB files is harder than customizing CSS.
Finally, font icons are infamous for not being that robust and
conflicting with UTF settings in certain browsers/devices. Recently Font
Awesome had a bug [3] because they added icons out of the Private Use
Area, and those icons could conflict with other UTF characters.
So, instead of loading Font Awesome icons with a font, we can add them
using their SVG files. There are several ways to do so, and all of them
solve the accessibility and robustness issues we've mentioned, so that
point won't be mentioned from now on.
All these techniques imply having to manually download Font Awesome
icons every time we upgrade Font Awesome, since the `font-awesome-sass`
gem doesn't include the `sprites/` and `svgs/` folders Font Awesome
includes in every release. So, from the maintenance poing of view,
they're all pretty lacking.
Method 1: SVG sprites with inline HTML
We can use SVG files where template icons are defined, like so:
<svg>
<use xlink:href="solid.svg#search"></use>
</svg>
This technique has great browser support and it only generates one HTTP
request for all icons. However, it requires adding <svg> tags in many
views, making it harder to customize for CONSUL installations. For
developers we could reduce the burden by adding a helper for these
icons.
Downloading all the icons just to use one (or a few) might also be
inconvenient, since the total file size of these icons will be up to a
megabyte. To reduce the impact of this issue, we could either minimize
the SVG file, compress it, or generate a file with just the icons we
use. However, generating that custom file would be harder to maintain.
Method 2: CSS with one SVG icon per file
We can use the separate SVG files provided by Font Awesome, like so:
background: url("solid/search.svg");
Or, if we want to add a color to the icon:
backgound: blue;
mask-image: url("solid/search.svg");
Using this technique will result in one HTTP request per icon, which
might affect performance. Browser support is also limited to browsers
supporting mask-image, which at the time of writing is 95% of the
browsers, with the notable exception of Internet Explorer 11.
On the plus side, using CSS makes it easy to customize and (IMHO) easy
to work with on a daily basis.
Method 3: CSS with SVG sprites
We can use the aforementioned sprites provided by Font Awesome and use
them with CSS:
backgound: blue;
mask-image: url("solid.svg#search");
The number of HTTP requests and file size are similar to Method 1, while
browser support, ease of customization and ease of use are similar to
Method 2.
There's one extra gotcha: this method requires doing minor changes to
the files provided by Font Awesome, which means this solution is harder
to maintain, since we'll have to do the same changes every time we
upgrade Font Awesome. Mainly we need to add these changes to every
sprite file:
- <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+<!--
+This is a modified version of Font Awesome Free regular sprite file.
The icons are exactly as they originally were; the only changes are:
+
+* <symbol> tags have been replaced with <svg> tags and a <style> tag
has been added
+* A <style> tag has been added
+* The style="display:none" attribute of the main <svg> tag has been
removed
+-->
+<svg xmlns="http://www.w3.org/2000/svg">
+ <style>
+ svg svg { display: none }
+ svg svg:target { display: inline }
+ </style>
And then replace every <symbol> tag with a <svg> tag.
Method 4: CSS with Data URI
Finally, we can write the icons directly in the CSS:
backgound: blue;
mask-image: url('data:image/svg+xml;utf8,<svg...');
This method does not generate any extra HTTP requests and only downloads
the icons we need. However, maintaining it is really hard, since we need
to manually copy all the <svg> code for every icon we use, and do it
again every time we upgrade Font Awesome.
In this commit, we implement Method 2. To improve browser support, we're
falling back to font icons on browsers which don't support mask images.
So 5% of the browsers might still conflict with users changing the fonts
or with screen readers trying to announce the icon character. We believe
this is acceptable; the other option for these browsers would be to show
those icons as a background image, meaning the icons would always be
black, meaning users of these browsers would have trouble to distinguish
them if the background was dark as well.
Since we aren't sure whether the performance hit of having one HTTP
request per icon is overcome by only requesting the icons we actually
use, we aren't taking this factor into account when choosing between
methods 2 and 3. We believe this method will be the less painful one to
maintain and customize. Generating SVG sprites with just the icons we
use would increase performance, but it would make it harder for existing
CONSUL installations to use icons we haven't included in the sprites.
[1] https://speakerdeck.com/ninjanails/death-to-icon-fonts
[2] https://developer.mozilla.org/en-US/docs/Web/CSS/content#Browser_compatibility
[3] https://blog.fontawesome.com/fixing-a-unicode-bug-in-5-14-0/
We were using `display: inline` assuming that's the way elements will be
displayed by default when shown. However, those elements could be
displayed in a different way (inline-flex, for instance). So we avoid
any possible conflicts by using the `display: none` rule when we want to
hide the elements.
Besides, the code is now symmetrical and IMHO easier to follow.
Even if "r" is shorter, "regular" is easier to understand, and we're
going to store these icons in a folder named "regular", which is the
convention Font Awesome uses.
After upgrading to Turbolinks 5, redirects are followed on AJAX
requests, so we were accidentally redirecting the user after they mark
an investment as visible to valuators.
There was already a system spec failing due to this issue ("Admin budget
investments Mark as visible to valuators Keeps the valuation tags");
however, it only failed in some cases, so we're adding additional tests.
Ideally we would write a system test to check what happens when users
click on the checkbox. However, from the user's point of view, nothing
happens when they do so, and so testing it is hard. There's a usability
issue here (no feedback is provided to the user indicating the
investment is actually updated when they click on the checkbox and so
they might look for a button to send the form), which also results in a
feature which is difficult to test.
So we're writing two tests instead: one checking the controller does not
redirect when using a JSON request, and one checking the form submits a
JSON request.
I've chosen JSON over AJAX because usually requests to the update action
come from the edit form, and we might change the edit form to send an
AJAX request (and, in this case, Turbolinks would handle the redirect as
mentioned above).
Another option would be to send an AJAX request to a different action,
like it's done for the toggle selection action. I don't have a strong
preference for either option, so I'm leaving it the way it was. At some
point we should change the user interface, though; right now in the same
row there are two actions doing basically the same thing (toggling
valuator visibility and toggling selection) but with very different user
interfaces (one is a checkbox and the other one a link changing its
style depending on the state), resulting in a confusing interface.
We removed it in commit d639cd58 because it recommended using `uniq`
where `distinct` was more appropriate. This has been fixed in
rubocop-rails 2.6.0.
This is something we should do everywhere because concurrent requests
might bypass Rails uniqueness validations. However, since there are
places where we aren't applying this rule and adding a unique index
means we also need to destroy any hypothetical duplicate records, it's
something we aren't going to solve right now. Therefore we use the
"refactor" severity so existing offenses don't get in our way.
In any case, we're adding the rule so we don't make the same mistake in
the future.
This rule was added in rubocop-rspec 1.39.0. The `visible: false` option
is equivalent to `visible: :all`, but we generally use it meaning
`visible: :hidden` for positive expectations and `visible: :all` for
negative expectations.
The only exceptations are tests where we count the number of map icons
present. I'm assuming in this case we care about the number of map icons
independently on whether they are currently shown in the map, so I'm
keeping the `visible: :all` behavior in this case.
By default, Capybara only finds visible elements, so adding the
`visible: true` option is usually redundant.
We were using it sometimes to make it an obvious contrast with another
test using `visible: false`. However, from the user's perspective, we
don't care whether the element has been removed from the DOM or has been
hidden, so we can just test that the visible selector can't be found.
Besides, using `visible: false` means the test will also pass if the
element is present and visible. However, we want the test to fail if the
element is visible. That's why a couple of JavaScript-dependant tests
were passing even when JavaScript was disabled.
These tests were supposed to check the link to vote is hidden when users
don't have permission to vote. However, they aren't testing that, since
the `visible: false` option also matches visible elements. The links are
actually considered visible since they're displayed by the browser;
there's just another element on top of them.
Using `obscured: true` instead of `visible: false` solves the issue.
However, while the `obscured` option is true when the element is hidden
by another element, it's also true when the element is not currently
visible in the browser window, so in some cases we need to scroll so the
condition is effective.
This rule was added in Rubocop 0.91.0. A similar rule named
LeakyConstantDeclaration was added in rubocop-rspec 1.34.0.
Note using the FILENAMES constant did not result in an offense using the
ConstantDefinitionInBlock rule but did result in an offense using the
LeakyConstantDeclaration rule. I've simplified the code to get rid of
the constant; not sure why we were adding a constant with `||=` in the
middle of a spec.
This rule was added in Rubocop 0.89.0. However, there are some false
positives when we don't use interpolation but simply concatenate in
order to avoid long lines. Even if there weren't false positives, there
are places where we concatenate to emphasize the point that we're adding
a certain character to a text.
We might reconsider this rule in the future, since we generally prefer
interpolation over concatenation.
The original devise_security_extension gem has not been maintained for
years. Its last release was version 0.10.0, and wasn't compatible with
Rails 5, and so we were using its master branch.
Since the gem was unmaintained, it was forked as devise-security and the
aforementioned master branch was released as version 0.10.1. This
version wasn't published in Rubygems, though, so we're now using the
first version that was published in Rubygems and had a release
announment [1].
Dependabot will probably open a pull request to upgrade to the latest
version, but for now I'm trying to keep the devise-security gem as
similar as the version we were using to make sure they're compatible,
particularly considering we're monkey-patching some of the modules
provided by this gem.
[1] https://github.com/devise-security/devise-security/releases/tag/v0.11.1
Using `travel` we go to `Time.now + interval`. If the application's time
zone changes due to seasonal clock changes during that interval, we
might travel to a time which is not the time we intended to travel to.
Example:
On a system using the UTC time zone, it's 9AM on October 25 (Friday).
Since by default CONSUL uses the Madrid time zone, it means the
application's time is 11AM.
We use `travel` to advance three days. That means we go to 9AM UTC on
October 28 (Monday). The application's time will be 10AM due to the
seasonal clock change, so we haven't fully traveled three days in
application's time.
To reproduce locally, run:
```
TZ=UTC rspec spec/system/proposal_notifications_spec.rb:410
```
Using `travel_to` with `3.days.from_now`, which uses the application's
time zone and so it will travel to October 28 at 11AM, solves the
problem.
