# 🧪 Running Tests in PyCharm (macOS + pytest-postgresql)

Our test suite uses `pytest` and `pytest-postgresql`, which
automatically spins up a temporary PostgreSQL instance.

On Linux (including GitHub Actions), PostgreSQL binaries are installed
in standard system locations.\
On macOS (Homebrew), they are not --- so PyCharm needs a small
configuration tweak to locate `pg_ctl`.

This guide explains how to run and debug tests locally in PyCharm
without modifying test code.

------------------------------------------------------------------------

## ✅ Prerequisites

### Devcontainer

Postgres install is included in the devcontainer, so no additional setup is needed.

Running

```bash
make test
```

Will instigate the test suite, which will automatically start a temporary PostgreSQL instance.

### Local MacOS

1. Install PostgreSQL via Homebrew:

``` bash
brew install postgresql
```

2. Confirm `pg_ctl` exists:

``` bash
which pg_ctl
```

Typical output:

    /opt/homebrew/bin/pg_ctl

------------------------------------------------------------------------

# 🚀 Running Tests in PyCharm

## Step 1 --- Create a PyCharm pytest Run Configuration

1. Open the test file.
2. Click the green ▶ next to the test.
3. Choose **"Edit Run Configuration..."**

You should see something like:

- **Target:** `backend/export/tests/test_export.py`
- **Working directory:** Project root (e.g.`Model/`)

------------------------------------------------------------------------

## Step 2 --- Add Required Override (macOS Only)

In the Run Configuration:

### ➜ "Additional Arguments"

Add:

    --override-ini=postgresql_exec=/opt/homebrew/bin/pg_ctl

This tells `pytest-postgresql` where `pg_ctl` lives on macOS.

Without this, PyCharm may fail with:

    ExecutableMissingException: Could not found pg_config executable

------------------------------------------------------------------------

## Step 3 --- Run or Debug

You can now:

- Click ▶ Run\
- Click 🐞 Debug\
- Set breakpoints normally

The temporary PostgreSQL instance will start automatically.

------------------------------------------------------------------------

# 🔍 Why This Is Needed

`pytest-postgresql` defaults to a Linux-style path:

    /usr/lib/postgresql/<version>/bin/pg_ctl

That path exists on Ubuntu (CI), but not on macOS.

On macOS, Homebrew installs PostgreSQL in:

    /opt/homebrew/bin/

The `--override-ini` flag safely overrides the executable path
**locally**, without modifying:

- test files\
- `conftest.py`\
- `pytest.ini`\
- CI configuration

This ensures:

- ✅ Tests still work in GitHub Actions\
- ✅ Tests still work for Linux users\
- ✅ macOS developers can debug in PyCharm\
- ✅ No repository-specific hacks are required

------------------------------------------------------------------------

# 🛠 Optional: Using a Local `.env` File

If you prefer not to hardcode the override in the run configuration:

1. Create a local file:

```{=html}
<!-- -->
```

    .env.local

2. Add:

```{=html}
<!-- -->
```

    PYTEST_ADDOPTS=--override-ini=postgresql_exec=/opt/homebrew/bin/pg_ctl

3. In PyCharm:
    - Open the Run Configuration
    - Add `.env.local` under **"Paths to .env files"**

------------------------------------------------------------------------

# 🧪 Running Tests via Terminal (Recommended for CI Parity)

For normal execution outside PyCharm:

``` bash
make test
```

These already work without additional configuration.

------------------------------------------------------------------------

# 🧠 Summary

Environment Works Without Override? Needs `--override-ini`?
  ------------------------ ------------------------- -------------------------
GitHub Actions (Linux)   ✅ Yes ❌ No
Linux local ✅ Yes ❌ No
macOS terminal (tox)     ✅ Yes ❌ No
macOS PyCharm debugger ❌ No ✅ Yes