> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UDS Testing

> Track and record urinalysis drug screening tests for residents, with result and test-type filtering at /rh/uds-tests.

The UDS Testing screen at `/rh/uds-tests` displays a filterable list of urinalysis drug screening (UDS) tests for the current organization and allows staff to record new tests via a dialog.

## Overview

The page loads UDS tests via `useUDSTests`, which queries the `rh_uds_tests` table joined to `rh_episodes` and `rh_uds_random_schedule`, scoped to `organization_id` (from `useOrganization`), ordered by `test_date` descending. The hook applies `episodeId` filtering server-side via the Supabase query builder; remaining filters (`result`, `isRandomTest`, `dateFrom`, `dateTo`) are applied client-side.

Filters available on the list page: free-text search input (wired to UI but not yet connected to `UDSTestFilters` in the observed code — the `Input` has no `onChange` handler setting the filter), result (`negative`, `positive`, `pending`), and test type (`Random`, `Scheduled`). The **Record Test** button opens `UDSTestDialog`. Individual rows navigate to `/rh/uds-tests/:id`. Creating a test also requires `RH_PERMISSIONS.UDS_TESTS_CREATE` (`rh.uds-tests.create`) for the create action — however this permission is not applied as a route-level gate; the button is shown to all users with `rh.dashboard.view`.

## Who it's for

No route-level `RequirePermission` beyond the outer `RHViewGuard` (`rh.dashboard.view`). `RH_PERMISSIONS.UDS_TESTS_CREATE` (`rh.uds-tests.create`) and `RH_PERMISSIONS.UDS_TESTS_EDIT` (`rh.uds-tests.edit`) exist in the permission constants but are not applied as route-level or button-level guards on this page in the observed code.

## Before you start

* Hold `rh.dashboard.view` to access the RH module.
* Understand your program's UDS testing policy before recording or interpreting results (confirm with SME).

## Steps

<Steps>
  <Step title="Open UDS Testing">
    Navigate to `/rh/uds-tests`. The table loads all UDS tests ordered by most recent test date first.
  </Step>

  <Step title="Filter by result">
    Use the **Result** dropdown to show only `Negative`, `Positive`, or `Pending` tests. Select "All Results" to clear.
  </Step>

  <Step title="Filter by test type">
    Use the **Test Type** dropdown to show only `Random` or `Scheduled` tests. Select "All Types" to clear. This maps to the `is_random` boolean on `rh_uds_tests`.
  </Step>

  <Step title="Search">
    The search input is present in the UI. Confirm with a subject-matter expert or the development team whether text search is active for this page.
  </Step>

  <Step title="View a test record">
    Click a row to navigate to `/rh/uds-tests/:id` for the full detail view including result, substances tested, and follow-up notes.
  </Step>

  <Step title="Record a new test">
    Click **Record Test**. The `UDSTestDialog` opens. Complete the form and save.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Result values">
    Observable result values: `negative`, `positive`, `pending`. A positive result on the detail page triggers a prompt to file a significant event.
  </Accordion>

  <Accordion title="Random vs scheduled tests">
    `is_random` is a boolean on `rh_uds_tests`. A random test references `rh_uds_random_schedule`. The `useRunRandomUDSSelection` hook exists in the hooks directory but is not used on this list page; its entry point within the module should be confirmed with a subject-matter expert or development team.
  </Accordion>

  <Accordion title="Client-side filtering">
    `useUDSTests` applies `result` and `isRandomTest` filters in JavaScript after the Supabase query returns, because of type inference limitations in the Supabase query builder with nested selects (documented in the hook source). `episodeId` is applied server-side.
  </Accordion>

  <Accordion title="42 CFR Part 2 sensitivity">
    UDS data in a substance use disorder treatment or recovery housing context may be subject to 42 CFR Part 2 SUD confidentiality protections. The applicability to this module and the required safeguards must be confirmed with a subject-matter expert and legal/compliance review.
  </Accordion>
</AccordionGroup>

## Viewing a UDS test

The UDS Test Details screen (`/rh/uds-tests/:id`) displays the complete record for a single UDS test. The page loads via `useUDSTestDetail`, which queries `rh_uds_tests` with a nested join to `rh_episodes` → `rh_resident_profiles` + `rh_residences`, and `rh_uds_random_schedule`, filtered by the `id` URL param.

Two cards are displayed side by side:

* **Test Information**: resident number (`episode.resident_profile.resident_number`), residence name, episode number, administered by (`collected_by`), and test date.
* **Result Summary**: result badge (`UDSResultBadge`), whether the test was random (`is_random`), and the list of substances tested (`substances_tested` array rendered as secondary `Badge` elements).

If `follow_up_notes` is present, a third card renders the note text. If the result is `positive`, a bordered destructive card is shown — "Positive Result — Follow Up Required" — with a link to `/rh/significant-events` and a note that a significant event should be reported.

Permission required: `rh.dashboard.view` via the outer `RHViewGuard`. `RH_PERMISSIONS.UDS_TESTS_EDIT` (`rh.uds-tests.edit`) exists in the permission constants but is not applied as a route-level guard on this path.

1. From `/rh/uds-tests`, click a row to open `/rh/uds-tests/:id`.
2. The **Test Information** card shows resident number, residence, episode number, the person who administered the test, and the test date/time.
3. The **Result Summary** card shows the result badge (`negative`, `positive`, or `pending`), whether it was a random test, and the substances panel tested.
4. If `follow_up_notes` are present, a dedicated card displays the note text.
5. If the result is `positive`, a destructive alert card prompts you to navigate to `/rh/significant-events`. Confirm the required follow-up process with a subject-matter expert.
6. Click **Back to UDS Tests** (visible on desktop) to return to `/rh/uds-tests`.

<AccordionGroup>
  <Accordion title="Result values">
    Observable result values: `negative`, `positive`, `pending`. Each is rendered by `UDSResultBadge` with an associated icon (`CheckCircle2` for negative, `AlertTriangle` for positive, `Clock` for pending).
  </Accordion>

  <Accordion title="Random vs scheduled test">
    The `is_random` boolean on `rh_uds_tests` indicates whether the test was part of a random selection. The `random_schedule` join references `rh_uds_random_schedule` for the associated schedule record.
  </Accordion>

  <Accordion title="Substances tested">
    The `substances_tested` field is stored as a string array. The specific substance panels used by your program should be confirmed with a subject-matter expert.
  </Accordion>

  <Accordion title="Positive result prompt">
    A positive result renders a hard-coded prompt to file a significant event. The clinical or compliance workflow required beyond this prompt should be confirmed with a subject-matter expert. 42 CFR Part 2 sensitivity questions should also be reviewed.
  </Accordion>

  <Accordion title="Resident number displayed">
    The detail page displays `resident_profile.resident_number` rather than a name, consistent with PHI minimization practices in the list and detail views.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Recovery Housing" icon="house" href="/rh/references">
    Recovery Housing references and overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/rh.tsx
  * src/cores/rh/pages/UDSTestsPage.tsx
  * src/cores/rh/pages/UDSTestDetailPage.tsx
  * src/cores/rh/hooks/useUDSTests.ts
  * src/cores/rh/hooks/useUDSTestDetail.ts
  * src/cores/rh/types/index.ts
</Accordion>