> For the complete documentation index, see [llms.txt](https://mozarkdocs.gitbook.io/appx_documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mozarkdocs.gitbook.io/appx_documentation/test-infrastructure-documentation/best-practices.md).

# Best Practices

## Best Practices

Use this page to follow recommended patterns for getting the most out of the Testing Portal.

### Organizing your work

* **Verify project context before starting** Check **Organization → App → Project** in the top navigation bar before launching sessions or uploading files.

  This quick check prevents data from being saved in the wrong place.
* **Name sessions clearly** Rename sessions as soon as they appear in the Sessions list.

  Good names include the feature, build version, and date.

  Example: `Checkout Flow – v2.4.1 – Regression`
* **Use tags consistently** Agree on a tagging taxonomy with your team.

  Examples include `smoke`, `regression`, `release-2.5`, and `priority-critical`.

  Consistent tags make filtering and historical search much easier.

### Bug filing

* **File bugs from within the session** The session runner captures context and links the current screenshot automatically.

  Filing later is possible, but it loses that automatic screenshot association.
* **Use priority and status consistently** Align on shared definitions with your team.

  A practical model is:

  * `Critical` blocks release
  * `High` breaks a core flow
  * `Medium` affects a secondary flow
  * `Low` is cosmetic or minor
* **Include reproduction steps** Always include preconditions, steps to reproduce, expected result, and actual result.

  This makes bugs faster to validate and fix.

### Using Optics AI effectively

* **Use Interact for targeted flows** Interact works best when you already know the flow you want to test.

  Write commands the way you would explain the task to a teammate.
* **Use Explorer for broad discovery** Explorer is a good first pass on a new build.

  Use it to identify broken paths before writing more detailed tests.
* **Start Explorer with low concurrency** Begin with `Concurrent = 2` on a new application.

  This helps you observe behavior before scaling up.

  Some applications rate-limit or block rapid parallel access.
* **Store credentials in Secrets, not Parameters** Parameters can appear in logs and reports.

  Secrets stay masked.

  Use Secrets for all credential values, including staging.

### File Management

* **Add metadata to every uploaded file** At minimum, include version, environment, and platform.

  Examples: `version`, `environment`, `platform`.
* **Do not delete files used by active suites** Check your Appium or Playwright configurations before deleting a file.

  Deleting a referenced file can break CI runs.

### Session reviews

* **Use quick-access modals for triage** Use **Video**, **Screenshots**, and **Bugs** from the Sessions list to review evidence quickly.

  Open full Session Details only when you need deeper context.
* **Use JQL for targeted reports** JQL is faster than manual scanning when you need precise session sets.

  Example: `status = "failed" AND user = "qa@example.com"`
* **Add notes immediately after sessions** Notes capture context while it is still fresh.

  Even short notes help preserve useful history.

### General tips

* Keep the Testing Portal in its own dedicated browser tab or window.
* Bookmark the Sessions list for your most-used project.
* Use **Admin Settings** in the user menu when expected data is missing and you need to verify project membership.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mozarkdocs.gitbook.io/appx_documentation/test-infrastructure-documentation/best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.