Verifying ThemeCompatibilityTest (TCT) Guide

Information about ThemeCompatibilityTest is available at: https://perfectsense.github.io/delivery-notes/modules/shared-test-descriptions.html#themecompatibilitytest

You can verify TCT is running by executing a build command on the project with brightspot.frontend.ThemeCompatibilityTest specified.

Example:

./gradlew ${PROJECT}-{site/web}:test --tests brightspot.frontend.ThemeCompatibilityTest

You should see output similar to this:

ThemeCompatibilityTest > Testing theme [{project}-theme-default] for compatibility with root styleguide STANDARD_OUT
    Scanning Directory... /{project-dir}/frontend/build/styleguide
    Scanned 277 files in 8359ms (33 files/s)
    Creating view definitions...
    Created 234 view definitions in 839ms (278 definitions/s)
    Scanning Directory... /{project-dir}/themes/{project}-theme-default/build/styleguide
    Scanned 150 files in 480ms (312 files/s)
    Creating view definitions...
    Created 89 view definitions in 37ms (2405 definitions/s)

ThemeCompatibilityTest > Testing theme [{project}-theme] for compatibility with root styleguide STANDARD_OUT
    Scanning Directory... /{project-dir}/themes/{project}-theme/build/styleguide
    Scanned 224 files in 688ms (325 files/s)
    Creating view definitions...
    Created 94 view definitions in 38ms (2473 definitions/s)

If it is not running, you may see:

• No output at all
• A scan of 0 files, that will look similar to the output below

ThemeCompatibilityTest > Testing theme [{project}-theme-default] for compatibility with root styleguide STANDARD_OUT
    Scanning Directory... /{project-dir}/frontend/build/styleguide
    Scanned 288 files in 7764ms (37 files/s)
    Creating view definitions...m 8s]
    Created 241 view definitions in 956ms (252 definitions/s)
    Scanning Directory... /{project-dir}/themes/{project}-theme-default/build/styleguide
    Scanned 0 files in 2ms (0 files/s) brightspot.frontend.ThemeCompatibilityTest
    Creating view definitions...
    Created 0 view definitions in 3ms (0 definitions/s)

If either of these are occurring, skip to the below troubleshooting section to fix the problem before proceeding with the upgrade.

After confirming that TCT is running, verify that TCT is legitimately flagging mismatches between the theme and root styleguide. To do this, simply introduce a new property into a JSON file under your theme bundle’s styleguide directory. For Example:

{ // themes/{project}-theme-default/core/article/ArticlePage.json
    ...,
    "dateModifieds": "this JSON field doesn't exist in the root styleguide for /styleguide/core/article/ArticlePage.json and should cause TCT to error",
    ...
}

Upon rebuilding the project (or running the test as you did earlier), you should see an error/warning similar to the one below.

ThemeCompatibilityTest > Testing theme [{project}-theme-default] for compatibility with root styleguide STANDARD_ERROR
    [core/article/ArticlePage.hbs] contains field(s) that do not exist in the root styleguide:
      [dateModifieds] at:
        core/article/ArticlePage.json at (line=6, col=18)

If TCT does not fail with an error like the one above, check the Troubleshooting section below. If after reviewing the troubleshooting you are still unable to cause TCT to intentionally fail, contact your Brightspot account representative for further guidance.

If TCT is Running With Errors:

If TCT is running as described above and failing with errors, set TCT to WARN mode. Fixing TCT errors is outside the scope of this guide and can be performed after the rest of the upgrade process is complete. Setting TCT to WARN mode will allow the upgrade to proceed without fixing TCT errors.

Setting TCT to WARN mode is accomplished differently depending on whether the codebase is already using the latest Brightspot Gradle plugin.

If the Brightspot Gradle Plugin Upgrade Guide has already been completed (and you're returning here to revisit TCT under one of the exception scenarios described at the top of this guide), modify the build.gradle for each frontend theme to contain:

bundle {
 testMode = 'warn'
}

If the Brightspot Gradle Plugin Upgrade Guide has not been completed, check the site/build.gradle or web/build.gradle file for gradle test configuration of ThemeCompatibilityTest, which would look like:

test {
    project.rootProject.allprojects.each {
        if (it.name.contains('-theme-')) {
            systemProperties.put('theme.' + it.name + '.compatibilityTestMode', 'warn')
        }
    }
}

Make sure the parameter after '.compatibilityTestMode' is 'warn' and not 'error'.

Once TCT is in WARN mode, continue to the next section of the Brightspot 4.5 Upgrade Guide, Step 3: Analyze and Resolve Shadowed Code.

If TCT is Running Without Errors:

If TCT is running as described above and no errors were encountered, move on to the next section of the Brightspot 4.5 Upgrade Guide, Step 3: Analyze and Resolve Shadowed Code.

This section describes common causes and resolution strategies of TCT not running or not catching errors during the verification step described above.

Styleguide: NoSuchFileException

Example error:

> Task :{project}-frontend:validateEmptyHandlebars FAILED
> Task :{project}-theme-default:yarnInstall UP-TO-DATE
FAILURE: Build failed with an exception.
* Where:
Script 'https://artifactory.psdops.com/psddev-releases/com/psddev/brightspot-gradle-plugins/root-styleguide-empty-handlebars/4.2.12/root-styleguide-empty-handlebars.gradle' line: 19
* What went wrong:
Execution failed for task ':{project}-frontend:validateEmptyHandlebars'.
> java.nio.file.NoSuchFileException: styleguide
* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.
* Get more help at https://help.gradle.org
BUILD FAILED in 4s
16 actionable tasks: 5 executed, 11 up-to-date

Resolution:

Remove the following line that lives under frontend/build.gradle:

apply from "https://artifactory.psdops.com/psddev-releases/com/psddev/brightspot-grade-plugins/root-styleguide-empty-handlebars/$brightspotGradlePluginVersion/root-styleguide-empty-handlebars.gradle"

TCT reports "Scanned 0 files in ..."

Example error:

ThemeCompatibilityTest > Testing theme [{project}-theme-default] for compatibility with root styleguide STANDARD_OUT
    Scanning Directory... {project-dir}/frontend/build/styleguide
    Scanned 288 files in 7764ms (37 files/s)
    Creating view definitions...m 8s]
    Created 241 view definitions in 956ms (252 definitions/s)
    Scanning Directory... {project-dir}/themes/{project}-theme-default/build/styleguide
    Scanned 0 files in 2ms (0 files/s) brightspot.frontend.ThemeCompatibilityTest
    Creating view definitions...
    Created 0 view definitions in 3ms (0 definitions/s)

First, find the location of the theme.zip file after building the project. In most cases, it will be under {theme-bundle-dir}/build/theme.zip. If this is not the case, please adjust the below code accordingly.

In either site/build.gradle or web/build.gradle (depending on the project, only one will exist), add or modify the lines containing def themeBuildDir and '.buildDir' to this configuration:

Resolution:

test {
    project.rootProject.allprojects.each {
        if (it.name.contains('-theme-')) {
            def themeBuildDir = it.buildDir.absolutePath + '/theme.zip'
            systemProperties.put('theme.' + it.name + '.buildDir', themeBuildDir)
            systemProperties.put('theme.' + it.name + '.compatibilityTestMode', 'error')
        }
    }
}

Java IllegalArgumentException

After setting the def themeBuildDir path to end with /theme.zip you may run into this error when running the test:

Example error:

ThemeCompatibilityTest > Testing theme [{project}-bundle-default] for compatibility with root styleguide FAILED
    java.lang.IllegalArgumentException at ThemeCompatibilityTest.java:96

Relevant Java error:

java.lang.IllegalArgumentException: Parameter 'directory' is not a directory

Resolution:

This may be due the project being on a version of com.psddev:component-lib that doesn't support .zip files. If the project is on a version of com.psddev:component-lib in the range [4.2.41, 4.2.187) then bump the project's componentLibVersion to 4.2.187 in the root build.gradle file. If the version is in the range [4.1.188, 4.2.0), skip to the next section of this guide, Step 3: Analyze and Resolve Shadowed Code and return to Verifying TCT after the rest of the upgrade.

FileAlreadyExistsException

After upgrading your com.psddev.component-lib version to resolve the above IllegalArgumentException (See troubleshooting section directly above), you may run into an issue with your build failing due to an exception: FileAlreadyExistsException

Open the gradle build error file and see which files it is failing to find.

Example error:

Below is an example of an error if applied to a .jpg file.

java.lang.RuntimeException: java.nio.file.FileAlreadyExistsException: /var/folders/60/q1yygjhn7g3gd276wh9x9g5m0000gp/T/{project}-bundle-default4884104514029138760/page/list/PageListB.json.jpg

Resolution - JS/CSS:

If the file is a js or css file, it might be missing the .min suffix in the file name. Add .min to the js or css files if they are missing this.

Example: IEPolyFills.js et. al.

In frontend/bundles/{project}-bundle-default/styleguide/page/Page-head.hbs:

if (!window.CSS || !window.CSS.supports || !window.CSS.supports('--fake-var', 0)) {
    var script = document.createElement('script');
    script.setAttribute('src', "{{cdn '/util/IEPolyfills.min.js'}}");
    script.setAttribute('type', 'text/javascript');
    script.async = false;
    head.appendChild(script);
    ...

if the .min suffix is missing from IEPolyfills.min.js above, add it. This change requires a corresponding change in frontend/bundles/{project}-bundle-default/webpack.commons.js:

entry {
    ...,
        'util/IEPolyfills.min.js': './styleguide/util/IEPolyfills.js',
    ...
}

Ensure that the JSON key above contains the .min suffix and the value does not (these are the target and source files for the webpack build process).

Other common similar scenarios may involve files such as:

• newsletter/NewsletterInline.css -> newsletter/NewsletterInline.min.css
• newsletter/NewsletterEmbed.css -> newsletter/NewsletterEmbed.min.css
• PreviewPage.css -> PreviewPage.min.css
• amp/Amp.js -> amp/Amp.min.js

Resolution - JPG

If the file the exception is citing is a .json.jpg file, you are running into an error because multiple styles are listed in the same config file using the same example file. You can remediate this by making a copy of the .json file in question, and using that copy as the example for one of duplicate style configurations. Repeat this process as necessary.

Example: _PageList.config.json Includes Two Styles With The Same Example

{
  "styles": {
    "/page/list/PageList.hbs": {
      "fields": [ ...],
      "templates": [
        ...,
        {
          "displayName": "List B",
          "example": "/page/list/PageListB.json",
          "height": 500,
          "width": 400,
          "fields": [
            "hideImage"
          ]
        }, ...
    },
    "/page/list/PageList.amp.hbs": {
      "templates": [
        {
          "displayName": "List Amp",
          "example": "/page/list/PageListB.json",
          "template": "/page/list/PageList.amp.hbs",
          "height": 800,
          "width": 1024
        }
      ]
    }
 }

1. Notice that in the _PageList.config.json file, both the /page/list/PageList.hbs and /page/list/PageList.amp.hbs templates use PageListB.json as an example.
2. Create a new file called PageListBCopy.json, and make it a copy of PageListB.json.
3. Replacing the example file with PageListBCopy.json in the /page/list/PageList.amp.hbs template configuration resolves the error.