Common Setup

  1. Ensure the Drupal module QA Accounts is in your project (i.e. in composer.json) and is enabled (or change the accounts located in qaUsers.json).
  2. For Playwright, set the baseURL in playwright.config.js. For Cypress, set the baseURL in cypress.config.js.

Entity Tests Setup

For these tests:

(ATK-XX-1110) Create, update, delete a node via the UI.

(ATK-XX-1120) Create, update, delete a taxonomy term via the UI.

(ATK-XX-1130) Create, update, delete an image via the UI.

Enable Automated Testing Kit so that the included hook can insert the nid, tid and mid into the page HTML.

Contact Us Test Setup

(ATK-XX-1050) Contact Us form accepts input, sends email uses Webform. Once the module is enabled, the default Contact Us form will be immediately available.

  • Form editing is located as admin/structure/webform
  • By default, the Contact Form is located at <your site>/form/contact
  • The settings for the Contact Form are at admin/structure/webform/manage/contact/settings
  • The email handling for the Contact Form is located at admin/structure/webform/manage/contact/handlers
  • To use this test, configure email sending with Symfony emailer and obtain an Ethereal.email account; place the email address and password from Ethereal into etherealUser.json.
  • There are two emails that are sent by default, the administrator notification email and the user confirmation email. (ATK-XX-1050) Contact Us uses the etherealUser.json user and checks only for the user confirmation email at Ethereal.email.

Error Page Tests Setup

(ATK-XX-1060) Validate 403 page appears expects:

  • create a Basic Page node with the alias /403-error-page with the Body containing the text "ATK 403 Error Page"
  • In admin/config/system/site-information, set Default Default 403 (access denied) page to"/403-error-page"

(ATK-XX-1061) Validate 404 page appears expects:

  • create a Basic Page node with the alias /404-error-page with the Body containing the text "ATK 404 Error Page"
  • In admin/config/system/site-information, set Default Default 404 (not found) page to"/404-error-page"

Media Entity Tests

(ATK-XX-1130) Create, update, delete an image via the UI expects:

  • Enable the Media module.

XML Sitemap

(ATK-XX-1070) Return # of sitemap files; fail if zero and (ATK-XX-1071) Regenerate sitemap files expect:

  • Enable the XML Sitemap module.

Setting Up Ethereal Email

If you will be testing round-trip emails (such as the registration or forgot password emails), set up an Ethereal.email account and configure the Drupal Symfony Mailer:

  1. Get an account here: https://ethereal.email/create
  2. Additional help with configuration is here: https://ethereal.email/help
  3. Install Drupal Symfony Mailer.
    1. Configure at admin/config/system/mailer/transport
    2. Add an SMTP transport mechanism:
      1. From the Transport type dropdown, select SMTP then click the Add transport button.
      2. Use the following configuration then click Save.

        Label: SMTP
        User name: <email_from_ethereal>
        Password: <password_from_ethereal>
        Host name: smtp.ethereal.email
        Port: 587
        Perform TLS peer verification: <your_choice>
      3. Set SMTP as the default. Click on the down arrow beside the Edit button of the SMTP transport then click Set as default.

Send a test email within Symfony Mailer:

  1. Once the configuration is complete (above), click Test in the module configuration or visit /admin/config/system/mailer/test.
  2. Enter an email address. The email won't be delivered but instead will be captured by Ethereal.email.
  3. Optionally change the email details by clicking the Edit button in the Test Email row.
  4. Click Send. You should see a message similar to:
    An attempt has been made to send an email to <email address>.
  5. Check for the email at https://ethereal.email/messages.

Once confirmed, change the values in etherealUser.json. See the Run Setup section of Installation/Uninstallation for the location of that file after running atk_setup.

Communicating with Pantheon

Communicating with Pantheon happens using Terminus. Install Terminus using this documentation at Pantheon. If you are using containers (such as Lando, DDev, Docksal or plain Docker) and are running tests inside the container, you will need to install and configure Terminus in the container.

When targeting Pantheon, do not change the drushCmd value in atk.config.js. The Kit will alter the Drush commands to work with Terminus.

Communicating to Remote Servers with Drush

Set up aliases using this Drush documentation. In the atk.config.js file (located in the project root after running atk_setup), change the line below from:

drushCmd: "drush"

to

drushCmd: "drush @alias"

This will pipe the drush commands to the remote server. If the destination is Pantheon, use the instructions above instead.

Cypress Framework Setup

  1. Install Cypress first; see Installation.
  2. Configure the cypress.config.js file:
    1. Set the baseUrl:

      module.exports = defineConfig({
        e2e: {
          baseUrl: 'https://performantlabs.com'
        }
      }
    2. (optional) Block common sites to prevent damaging site traffic analytics when running tests; edit as needed:

      module.exports = defineConfig({
      e2e: {
      baseUrl: 'https://performantlabs.com'
      },
      blockHosts: [ "www.google-analytics.com", "stats.g.doubleclick.net", "www.google.com", "connect.facebook.net", "www.facebook.com", "px.ads.linkedin.com", "www.linkedin.com", "www.googletagmanager.com",
      ]
    3. Add the the require() functions for cypress-log-to-term and cypress/grep:

      e2e: {
      baseUrl: 'https://performantlabs.com', setupNodeEvents(on, config) { // register the "cypress-log-to-term" plugin // https://github.com/bahmutov/cypress-log-to-term // IMPORTANT: pass the "on" callback argument require('cypress-log-to-term')(on)
      require('@cypress/grep/src/plugin')(config);
      return config; } }
    4. Cypress-log-to-term requires that a task be set up:

      e2e: {
      baseUrl: 'https://performantlabs.com', setupNodeEvents(on, config) { // Register the "cypress-log-to-term" plugin. // https://github.com/bahmutov/cypress-log-to-term // IMPORTANT: pass the "on" callback argument require('cypress-log-to-term')(on)
      require('@cypress/grep/src/plugin')(config);
      on('task', {
      log(message) {
      console.log(message)
      return null
      } })
      return config; }
       
    5. Create an account at Ethereal.email by visiting https://ethereal.email/create.
    6. If using a developer container tool such as DDEV, Lando or Docksal, use one of the following in the cypress.config.js file:

      "drushCmd": "ddev drush"
      "drushCmd": "lando drush" "drushCmd": "fin drush"
    7. If using Pantheon hosting, tell ATK that the target site is on Pantheon by setting isTarget to true. Also specify the target site name (not the site URL) and the environment (usually "dev," "test" or "live").

      With these properly set, the Drush commands will be piped to your Pantheon site via the Terminus command. 

      pantheon : {
        isTarget: true,
        site: "<site_name>",
        environment: "dev"
      }                               

Playwright Framework Setup

  1. Install Playwright first; see Installation
  2. Configure the playwright.config.js file.

    1. Set the baseUrl:
    module.exports = defineConfig({
      use: {
        /* Base URL to use in actions like `await page.goto('/')`. */
        baseURL: 'https://performantlabs.com',
        ...
    }
    }