Create Web Template and Flow Integration Tests with Sitecore Personalize

Welcome back, friends! A few weeks ago, I introduced a new SDK I created for testing Sitecore Personalize. If you missed it, check out the original post: Introduction to Sitecore Personalize SDK and Testing (dylanyoung.dev). Today, we're diving deeper into Web Template automated integration tests using the SDK. We'll also explore the current APIs that make this approach possible.

As mentioned in my previous blog post, Sitecore Personalize offers various asset types, each requiring different integration testing methods. While our current testing capabilities are limited, they provide a solid foundation for ensuring the quality of our personalization efforts.

Web Template Testing

The new SDK introduces numerous ways to test Sitecore Personalize after successful deployment or on a periodic basis. For web templates specifically, there are two APIs—and consequently, two methods—accessible through the SDK that facilitate testing templates post-deployment:

• TestNewTemplate (Preview template code | Sitecore Documentation)
• TestExistingTemplate (Preview templates | Sitecore Documentation)

TestNewTemplate

While this method may not be essential for integration testing, it proves invaluable for local integration testing when developing a new template. This approach assumes you've adopted a workflow where templates are built locally in source control and then deployed to your Personalize tenant. The function allows you to input your template's structure along with template parameters. It then returns the rendered result and indicates any issues encountered during template execution.

Let's take a closer look at how to use this method with the SDK. Here's an example:

Copy
1const templateElements: ITemplateElement[] = [
2  {
3    id: "js",
4    template: "<script>console.log('Hello from template')</script>",
5  },
6  {
7    id: "html",
8    template: "<h1>Hello [[Title | string]]</h1>",
9  },
10];
11
12const templateResult = await personalizeClient.Templates.TestNewTemplate(
13  templateElements,
14  { Title: "London" }
15);
16
17if (templateResult?.templates) {
18  console.log(JSON.stringify(templateResult.templates));
19}

This code showcases the TestNewTemplate method from the Sitecore Personalize SDK for testing a new web template. It creates template elements using HTML and JavaScript, then invokes the method with these elements and a parameter. If templates are returned, the result is logged. For guidance on initializing the Personalize SDK, check out my previous article where I delved into this topic.

The results of that request are shown below. As you can see, because I passed in template variables with Title set to London, this value now appears in the response.

Copy
1[
2  { id: "js", template: "<script>console.log('Hello from template')</script>" },
3  { id: "html", template: "<h1> Hello London</h1>" },
4];

TestExistingTemplate

This method proves more valuable for post-deployment or ongoing integration testing scenarios. You can find the documentation for this endpoint (also available in the SDK) here: Preview templates | Sitecore Documentation. The method focuses on templates already existing within Sitecore Personalize. It allows you to input custom template variables, enabling you to verify that the rendered template—with your specified variables—aligns with your expectations.

So lets explore how we would call this in the Personalize SDK:

Copy
1const templateResults = await personalizeClient.Templates.TestExistingTemplate(
2  "example_web_template",
3  { "Alt Description": "London" }
4);
5
6console.log(JSON.stringify(template?.renderedTemplates));

For this scenario, we need an existing template. We can use the template's friendly ID (only) to reference it. The HTML of the web template I used looks like this:

Copy
1<!-- define the structure and content of your Experience in HTML e.g.-->
2<div>[[Alt Description | text | | {order: 1, required: false} ]]</div>
3<!-- Use dynamic Guest variables, type ctrl+space or guest to explore available entities.-->
4<!-- Type 'd' to see decisioning helpers -->

This means when I passed in Alt Description, it was injected into my Web Template, providing a valid response. This approach is valuable as it allows you to test and verify that an existing template functions as expected. I'll delve into specific strategies for integration testing in a future post. Below, you can see the output of the code we just discussed:

Copy
1{
2    "test": [
3        {
4            "id": "js",
5            "template": "// You can choose how you want to add your HTML by using insertHTMLBefore, insertHTMLAfter, or replaceHTML methods\n// e.g insertHTMLAfter('.someClassName'); or insertHTMLAfter('body'); or replaceHTML('#myPageId')\n\n/*\n\n(function () {\n  // Add statements here\n})();\n\n*/"
6        },
7        {
8            "id": "css",
9            "template": "/** style your Experience with CSS */"
10        },
11        {
12            "id": "html",
13            "template": "<!-- define the structure and content of your Experience in HTML e.g.-->\n<div>London</div>\n<!-- Use dynamic Guest variables, type ctrl+space or guest to explore available entities.-->\n<!-- Type 'd' to see decisioning helpers -->\n"
14        },
15        {
16            "id": "freemarker",
17            "template": "<#-- Construct the API request body using Freemarker -->\n<#-- For your Experience to run your API tab must have, at a minimum, open and closing brackets -->\n{  <#-- Freemarker will go here -->   }"
18        }
19    ]
20}

As demonstrated above, when we set the Alt Description parameter to London in our TestExistingTemplate request, the template output reflects this change—replacing the placeholder with "London" in the rendered HTML.

Flow (Experience/Experiment) Testing

TestTemplate

I considered omitting this endpoint, but it could be a valuable feature for some developers. It's not currently supported by the SDK because the API doesn't work with the new developer-generated API tokens I've discussed in a previous post: Sitecore Personalize: New Developer Focused API Keys (dylanyoung.dev). Due to this lack of support, the only way to use it is by authenticating with your personal login—which isn't ideal if you're aiming to automate your development workflow.

What makes this API noteworthy—and potentially worth exploring in a future blog post—is its ability to execute your code, not just process template variables like the two examples above. If you have conditions or other logic, it will parse the code and output any errors that arise, as well as any debug messages you've included in your code (e.g., print('some message');).

That wraps up today's topic. Stay tuned for more content showcasing the capabilities of the SDK!