Open a debug session

A debug session is a live connection between a page of your app and the portal. While a page has one, your team can run a test suite or a single action in that page, with the session of the user who is signed in there. A page opens a debug session when its install has the debug flag and its environment allows debug sessions.

Before you begin

• The agent is installed in your app. See Installation.
• Use an environment that is not Production, with test data. Debug sessions are off on Production by default.

Add the debug flag to the install

The Debug mode switch on the install card writes the flag into the snippet for you.

1. In the portal, go to Web Agents and select your agent.
2. In the Overview tab, find the Install the assistant card and turn on Debug mode.
3. Copy the snippet of the tab you installed with and replace the one in your app.

The flag is &debug=1 on the script URL, or debug: true in Faustine.init. Keep the environment your install already names.

<script src="https://webagent.faustine.ai/embed?wid=<AGENT_ID>&env=Staging&debug=1" async></script>

<script src="https://webagent.faustine.ai/loader.js"></script>
<script>
  Faustine.init({ agentId: '<AGENT_ID>', env: 'Staging', debug: true });
</script>

import Faustine from '@faustine-ai/web-agent';

export const agent = Faustine.init({
  agentId: '<AGENT_ID>',
  env: 'Staging',
  debug: true,
});

Do not ship the flag in the install your users load. Set it from a build variable, or keep it in a development build only.

Open the session

1. Open your app in a browser and sign in as the user the tests should run as.
2. Leave the tab open.

The page shows a banner that starts with "Faustine debug mode is on" for as long as the session is attached. The visitor can close the banner. It comes back with the next session.

In the portal, the session appears in two places:

• In the Tests tab, inside each suite that is ready, under Live debug session. The row shows the page's domain, the identified user, the page title, the environment, the version the page loaded and the browser.
• In the Actions tab, where each enabled action gets a Test button.

The session ends when the tab closes or navigates away from your app. A page that reloads opens a new one.

Allow debug sessions on an environment

Each environment has a Debug sessions switch. It is on for every environment except Production. A page of an environment where the switch is off does not open a session, even with the flag.

To change it:

1. In the agent's header, select the control that lists each environment with the version it serves. The Deployments dialog opens.
2. Under the environment, turn Debug sessions on or off.
3. Select Apply changes.

Troubleshooting

Next steps

• Generate and run a test suite: run a suite in the session.
• Turn an action on or off and test it: run one action in the session.
• Tests: what a suite is and how a run works.