https://docs-production-katalon.netlify.app/assets/js/0ea6122a.9fcf3bc4.js

1"use strict";(self.webpackChunkKatalon_Docs=self.webpackChunkKatalon_Docs||[]).push([[11925],{28453:(e,t,s)=>{s.d(t,{R:()=>a,x:()=>o});var n=s(96540);const i={},r=n.createContext(i);function a(e){const t=n.useContext(r);return n.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function o(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:a(e.components),n.createElement(r.Provider,{value:t},e.children)}},71595:(e,t,s)=>{s.r(t),s.d(t,{assets:()=>l,contentTitle:()=>o,default:()=>u,frontMatter:()=>a,metadata:()=>n,toc:()=>c});const n=JSON.parse('{"id":"test-case-generation-with-truetest/user-session-attributes","title":"Set user session attributes","description":"While TrueTest captures user interaction data on an AUT, this data is often generic and lacks the business-specific context teams need, such as user roles, feature flags, experiment groups, or user IDs.","source":"@site/docs/katalon-truetest/test-case-generation-with-truetest/user-session-attributes.md","sourceDirName":"test-case-generation-with-truetest","slug":"/test-case-generation-with-truetest/user-session-attributes","permalink":"/katalon-truetest/test-case-generation-with-truetest/user-session-attributes","draft":false,"unlisted":false,"tags":[],"version":"current","lastUpdatedAt":1790870864000,"frontMatter":{"title":"Set user session attributes"},"sidebar":"katalon-truetest","previous":{"title":"Traffic levels","permalink":"/katalon-truetest/test-case-generation-with-truetest/traffic-levels"},"next":{"title":"Test Gap Analysis","permalink":"/katalon-truetest/test-case-generation-with-truetest/test-gap-analysis"}}');var i=s(74848),r=s(28453);const a={title:"Set user session attributes"},o=void 0,l={},c=[{value:"Use cases",id:"use-cases",level:2},{value:"Installation",id:"installation",level:2},{value:"Set session attributes",id:"set-session-attributes",level:2},{value:"Usage",id:"usage",level:4},{value:"Generate map with custom attributes filter",id:"generate-map-with-custom-attributes-filter",level:2},{value:"Known limitations",id:"known-limitations",level:2}];function d(e){const t={a:"a",admonition:"admonition",code:"code",em:"em",h2:"h2",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(t.p,{children:"While TrueTest captures user interaction data on an AUT, this data is often generic and lacks the business-specific context teams need, such as user roles, feature flags, experiment groups, or user IDs."}),"\n",(0,i.jsx)(t.p,{children:"To improve the relevance and accuracy of generated test cases, TrueTest allows users to inject custom attributes into a user session. These attributes are attached to the session metadata and stored alongside interaction data in TrueTest."}),"\n",(0,i.jsx)(t.h2,{id:"use-cases",children:"Use cases"}),"\n",(0,i.jsx)(t.p,{children:"A few use cases where you can leverage this feature are:"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:["User role-based testing: Sessions are tagged with ",(0,i.jsx)(t.code,{children:"userRole: admin"}),", ",(0,i.jsx)(t.code,{children:"userRole: viewer"}),", etc. Testers generate separate test cases for different roles to ensure coverage of role-specific behavior or access controls."]}),"\n",(0,i.jsxs)(t.li,{children:["User-level debugging: Sessions are tagged with ",(0,i.jsx)(t.code,{children:"userId: 87654"}),". QA can quickly isolate and analyze issues reported by specific users, then generate a test case that replicates the exact path they took."]}),"\n",(0,i.jsxs)(t.li,{children:["A/B experiment validation: Sessions are labeled with ",(0,i.jsx)(t.code,{children:"experimentGroup: A"})," or ",(0,i.jsx)(t.code,{children:"experimentGroup: B"}),". QA filters by group to generate tests tailored to each variation and ensure both versions are functionally covered."]}),"\n"]}),"\n",(0,i.jsx)(t.p,{children:"This document shows you how to set up custom session attributes and use them in your generated user sessions."}),"\n",(0,i.jsx)(t.h2,{id:"installation",children:"Installation"}),"\n",(0,i.jsxs)(t.p,{children:["Add the following snippet to your HTML ",(0,i.jsx)(t.code,{children:"<head>"}),". Replace with your own client code in the ",(0,i.jsx)(t.code,{children:"client-code"})," field."]}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-jsx",children:'<script defer async client-code="KA-2477-2" src="https://static.katalon.com/libs/traffic-agent/v1/traffic-agent.min.js"><\/script>\n<script src="https://static.katalon.com/libs/traffic-agent/v1/truetest-sdk.min.js"><\/script>\n'})}),"\n",(0,i.jsx)(t.h2,{id:"set-session-attributes",children:"Set session attributes"}),"\n",(0,i.jsx)(t.p,{children:"Follow this template to inject attributes via JavaScript."}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-jsx",children:'TrueTest.setSessionAttributes({\n    session_name: "Complete checkout with promo code",\n    session_description: "User adds items to cart, applies discount promo, and completes payment.",\n    userRole: "admin",\xa0\n    experimentGroup: "B",\n    userId: "user_1234",\n});\n'})}),"\n",(0,i.jsx)(t.h4,{id:"usage",children:"Usage"}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Reserved attributes:"})," If provided, TrueTest stores and uses these attributes internally. These are standard fields required for identifying and describing a test session."]}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.code,{children:"session_name"}),": TrueTest uses this value as the ",(0,i.jsx)(t.strong,{children:"Flow Name"})," during flow generation."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.code,{children:"session_description"}),": TrueTest uses this value as the ",(0,i.jsx)(t.strong,{children:"Flow Description"})," during flow generation."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.code,{children:"session_name"})," supports up to 60 characters and ",(0,i.jsx)(t.code,{children:"session_description"})," supports up to 120. If they exceed the limits, the system will fall back to AI-generated values instead."]}),"\n",(0,i.jsx)(t.li,{children:"Test cases generated from these custom flows will use the same name and description."}),"\n"]}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Custom attributes:"})," ",(0,i.jsx)(t.code,{children:"userRole"}),", ",(0,i.jsx)(t.code,{children:"experimentGroup"}),", ",(0,i.jsx)(t.code,{children:"userId"}

1)," are user-defined metadata that you attach to a session to get insight of user behavior."]}),"\n",(0,i.jsx)(t.admonition,{type:"note",children:(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:["Only ",(0,i.jsx)(t.strong,{children:"key-value pairs"})," are supported."]}),"\n",(0,i.jsxs)(t.li,{children:["Each ",(0,i.jsx)(t.strong,{children:"key can have only one value"})," per session. Arrays or lists of values are not supported."]}),"\n",(0,i.jsxs)(t.li,{children:["Each key can have multiple values if set more than once. All unique, non-empty values are trimmed and collected into an array (For example, ",(0,i.jsx)(t.code,{children:'userRole = ["admin", "editor"]'}),")."]}),"\n"]})}),"\n",(0,i.jsx)(t.h2,{id:"generate-map-with-custom-attributes-filter",children:"Generate map with custom attributes filter"}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsxs)(t.li,{children:["When creating a new user journey map, define queries in the ",(0,i.jsx)(t.strong,{children:"Filter by user session attributes"})," field to target specific sessions based on your custom attributes."]}),"\n"]}),"\n",(0,i.jsxs)(t.p,{children:["You can use the same attribute query syntax to find sessions on the ",(0,i.jsx)(t.strong,{children:"User Sessions (beta)"})," page before generating test cases directly from those sessions. See ",(0,i.jsx)(t.a,{href:"/katalon-truetest/test-case-generation-with-truetest/generate-test-cases-from-user-sessions",children:"Generate test cases from User Sessions"}),"."]}),"\n",(0,i.jsx)("img",{width:"500",alt:"Generate map with attributes filter",src:"https://tw-cdn.katalon.com/truetest/custom-session-attributes/generate-map-with-attribute-filter.png"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:["You can combine multiple conditions using ",(0,i.jsx)(t.code,{children:"AND"})," and ",(0,i.jsx)(t.code,{children:"OR"}),"."]}),"\n",(0,i.jsxs)(t.li,{children:["Use ",(0,i.jsx)(t.code,{children:"NOT"})," before one condition or a parenthesized group to exclude matching sessions. Operator precedence is ",(0,i.jsx)(t.code,{children:"NOT"}),", then ",(0,i.jsx)(t.code,{children:"AND"}),", then ",(0,i.jsx)(t.code,{children:"OR"}),". Parentheses can override this order."]}),"\n",(0,i.jsxs)(t.li,{children:["A negated condition includes otherwise eligible sessions that do not contain the referenced attribute. For example, ",(0,i.jsx)(t.code,{children:"NOT userRole = 'admin'"})," includes a session without a ",(0,i.jsx)(t.code,{children:"userRole"})," value."]}),"\n",(0,i.jsx)(t.li,{children:"Example queries:"}),"\n"]}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-jsx",children:"userRole = 'admin' AND experimentGroup = 'B'\nNOT userRole = 'admin'\nNOT (webdriver = 'true' OR environment = 'test')\n"})}),"\n",(0,i.jsxs)(t.ol,{start:"2",children:["\n",(0,i.jsx)(t.li,{children:"After you generated the journey map, you can filter the user flows with predefined attributes of the related user sessions."}),"\n"]}),"\n",(0,i.jsx)("img",{width:"800",alt:"Filter by attributes",src:"https://tw-cdn.katalon.com/truetest/custom-session-attributes/filter-by-custom-attributes.png"}),"\n",(0,i.jsxs)(t.p,{children:["Click the ",(0,i.jsx)(t.strong,{children:"View test steps"})," button to view custom attributes for each flow if they are available."]}),"\n",(0,i.jsx)("img",{width:"800",alt:"View session attributes in Flow view",src:"https://tw-cdn.katalon.com/truetest/custom-session-attributes/view-session-attributes-in-flow-view.png"}),"\n",(0,i.jsx)(t.h2,{id:"known-limitations",children:"Known limitations"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Data transmission"}),": Custom attributes collected by the agent will be sent as per individual request. Performance optimization through request bundling will be planned for a future version."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Data privacy"}),": By default, TrueTest does not store or retain any sensitive information. All test case generation filters out sensitive data automatically. However, if you manually add them via custom attributes, those attributes will be stored as entered. We recommend avoiding the use of sensitive data in custom attributes."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Conditional Test Generation"}),": Currently, custom attributes can only be used for capturing and filtering sessions, not for analytics or c

1onditional test generation."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Delayed \u201cNo Data\u201d Error"}),': In some cases, when you generate a map with a custom attribute filter, they have to wait, only to get a "no data" error message later. This happens because we first download all sessions in the time range, ',(0,i.jsx)(t.em,{children:"then"})," check if they match the attribute filter, instead of validating everything at once."]}),"\n"]})]})}function u(e={}){const{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}}}]);