TA Stuff - acquia/acquia_cms GitHub Wiki

One does not simply add a dependency

Everything needs to have automated tests

Do things the Drupal way, except when we can't

You're not going to need it

It's better to fail hard

Testing is critically important in this project, and it will be different than what would be done in a normal Professional Services project. This is because we're not building a site that will be deployed, and then maintained -- we are building a product that will improve over time, that will be used in ways we might not be able to fully predict. We care about making sure that the features we're building work well, and continue to work well even as the project changes. As a developer on this project, you are going to be acting more like a contributed module author than a site builder.

For testing, we will be using Drupal's PHPUnit testing framework. This is the same framework used by Drupal core and all contributed modules. Don't be fooled by the word "unit" in "PHPUnit" -- we are not only, or even mostly, going to be writing unit tests. PHPUnit is very flexible and can be used for several different kinds of testing. Drupal takes full advantage of that flexibility. The tests you write will be isolated, which means each individual one will install a completely new Drupal, with content in it and no modules installed. In your tests, you will set up the stuff you need (modules, config, etc.) at the beginning of the test.

The reason for this is to ensure that you are testing only what you intend to be testing, and that it works exactly as it should. Don't worry -- it's nowhere near as difficult to do this set-up work as you might think. Your tests should set up ONLY what they need in order to test the thing they're trying to test.

There are four kinds of tests you can write, and I'm ranking them in order from most useful to least useful:

  • Functional: These tests are reasonably fast and very stable. They provide comprehensive coverage, because they test what a user will actually see and how users will actually interact with your code. The one caveat with these tests is that they do not support JavaScript in any way, shape or form.
  • Functional JavaScript: These are slower than functional tests, and less stable -- they are prone to random failures. That instability means they are harder to write correctly, and potentially harder to debug. They provide very comprehensive coverage, but their relative trickiness and brittleness means we shouldn't favor them. In these tests, you can interact with pages that use JavaScript.
  • Kernel: These tests are best for testing lower-level code. They don't let you interact with actual pages, but you can interact with Drupal's API and any enabled module at the code level. You can also interact with the database. However, because these aren't directly testing the user experience, they aren't always the most valuable test. They can be useful for testing certain bugs, though.
  • Unit: These tests let you test low-level code, but without the benefit of Drupal's API, or modules. There is no database available to you in these tests, and they can be overwhelmingly complicated to write (especially when testing Drupal code). Line per line, these offer the least amount of test coverage for the effort involved. Their only benefit is that they are VERY fast, but generally that speed boost is not worth it (the other types of tests are surprisingly quick).

How to implement cloud hooks:

Cloud Hooks are scripts in your code repository Cloud Platform executes on your behalf when a triggering action occurs. With Cloud Hooks, you can automate tasks.

External links: https://github.com/acquia/blt/tree/12.x/scripts/cloud-hooks/hooks/common https://docs.acquia.com/cloud-platform/develop/api/cloud-hooks/ https://docs.acquia.com/tutorials/deploy/post-code-deploy/

How to manage hook_update

Developers should make sure that their changes have a corresponding hook_update.

Example: If you wish to change the site name, create a hook update, which you can add in either development or common module.

External links: https://www.drupal.org/docs/drupal-apis/update-api/updating-database-schema-andor-data-in-drupal-8 https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Extension%21module.api.php/function/hook_update_N/9.0.x

One should not remove methods without an hook update.

Update path is very important if we are removing an already existing method, since there can be an impact on currently installed sites.

Example scenario: In one of the development cases the team removed a function called 'ACMSConfigOverrides'. On deployment, this change broke any currently installed sites, since cache_container is loaded early in the bootstrap, and that function was called very early. A hook_update may not even have worked in that particular scenario. As part of that JIRA ticket, we would have caught the issue, had we been maintaining an update path, and we would have had to create a fix. The method used was to fix this was, drush @acmsbeta.prod --uri=http://startertest.acmsbeta.acsitefactory.com/ sql-query "delete from cache_container where data like '%ACMSConfigOverrides%';", and then the sites stopped WSOD.

@TODO Add some scenarios from ACMS. Refer to the example scenario explained above.

Troubleshooting and release notes for update paths

For any new code addition or removal in a ticket, there should be a corresponding db update hook, which will be used to test that feature on a separate branch and environment. We have put a condition, such that drush updb runs only on update path encironment.

By running this hook update we will be able to detect any issues that may arise.

Process for including information in tickets.

if a JIRA ticket includes a potentially breaking change, documentation should be written in the jira task to include common failure fixes.