# La Suite Docs Tests

## Requires

- keycloak

## Target

- **URL:** https://lasuite-docs.<DOMAIN_SUFFIX>
- **Keycloak:** https://keycloak.<DOMAIN_SUFFIX> (realm: `lasuite-docs`)

## Prerequisites

Keycloak (`keycloak.<DOMAIN_SUFFIX>`) must be deployed before testing lasuite-docs. The OIDC login test and any manual authentication testing depend on it. If Keycloak is not running, deploy it first with `/recipe-deploy keycloak`.

## Automated Checks

Run the scripts in `tests/` to perform automated testing:

- `tests/health_check.py` — Confirms the instance is reachable and returns HTTP 200.
- `tests/oidc_login.py` — Tests the full OIDC authentication flow end-to-end:
  1. Verifies Docs' `/api/v1.0/authenticate/` redirects to Keycloak
  2. Obtains an access token from Keycloak via direct access grant (password flow)
  3. Calls Docs' `/api/v1.0/users/me/` with the token and verifies the correct user is returned

  This test reads credentials from `keycloak-test-credentials.<DOMAIN_SUFFIX>.toml`.

## Keycloak OIDC Integration

La Suite Docs **requires** an OIDC provider. The test instance uses Keycloak at `keycloak.<DOMAIN_SUFFIX>`.

### Setup

Run `setup_keycloak_integration.py` to configure everything automatically. The script:

1. Creates a `lasuite-docs` realm in Keycloak
2. Creates a `docs` OIDC client (confidential, standard flow + direct access grants)
3. Creates a test user (`testuser` / `testpass123`)
4. Inserts the OIDC client secret into the Docs app via `abra app secret insert`
5. Updates the Docs env file with `OIDC_REALM`, `AUTH_DOMAIN`, `OIDC_RP_CLIENT_ID`
6. Writes all credentials to `keycloak-test-credentials.<DOMAIN_SUFFIX>.toml`

After running the setup script, redeploy Docs:

```
abra app deploy lasuite-docs.<DOMAIN_SUFFIX> --chaos --force --no-input
```

The script is idempotent — it skips resources that already exist and resets the test user password.

### Credentials

All Keycloak credentials are stored in `keycloak-test-credentials.<DOMAIN_SUFFIX>.toml` (sourceable):

| Variable | Description |
|----------|-------------|
| `KC_ADMIN_USER` / `KC_ADMIN_PASS` | Keycloak admin (master realm) |
| `KC_REALM` | Keycloak realm name (`lasuite-docs`) |
| `KC_CLIENT_ID` / `KC_CLIENT_SECRET` | OIDC client ID and secret |
| `KC_TEST_USER` / `KC_TEST_PASS` | Test user credentials |
| `KC_TEST_EMAIL` | Test user email |

### Key Endpoints

| Endpoint | Purpose |
|----------|---------|
| `https://lasuite-docs.<DOMAIN_SUFFIX>/api/v1.0/authenticate/` | Initiates OIDC login (302 redirect to Keycloak) |
| `https://lasuite-docs.<DOMAIN_SUFFIX>/api/v1.0/callback/` | OIDC callback (Keycloak redirects here after login) |
| `https://keycloak.<DOMAIN_SUFFIX>/realms/lasuite-docs/protocol/openid-connect/token` | Keycloak token endpoint |

## Post-Deploy Steps

After deploying Docs for the first time:

1. **Keycloak integration:** `python3 recipe-info/lasuite-docs/setup_keycloak_integration.py` then redeploy

Migrations and Minio buckets are created automatically on startup — no manual steps needed.

## Manual Verification

1. Open https://lasuite-docs.<DOMAIN_SUFFIX> in a browser.
2. Confirm the La Suite Docs landing page loads without errors.
3. Click "Login" and verify the OIDC redirect to Keycloak works.
4. Log in with test credentials (`testuser` / `testpass123`).
5. After logging in, verify you can create and edit a document.