# Manual Test Instructions

## Alpaca Daily Fetcher

This test checks the Alpaca data fetcher and confirms it writes a symbol-named Parquet file.

The fetcher currently requests:

- symbol: provided as a command line argument;
- end date: provided with `--end-date YYYYMMDD`, defaulting to yesterday;
- end date can also be derived with `--end-date-from-parquet`;
- duration: provided with `--duration`, defaulting to `1 W`;
- bar size: `1 day`;
- data source: Alpaca stock bars through `alpaca-py`;
- output: a Parquet file in `data/alpaca/daily/`.

## Prerequisites

1. Create or confirm Alpaca API credentials.
2. Provide credentials through `ALPACA_API_KEY` and `ALPACA_SECRET_KEY`, a local `.env`, or CLI arguments.
3. Sync Python dependencies:

```sh
mise exec -- uv sync
```

## Run The Test

From the repository root, run:

```sh
mise exec -- uv run python src/trading_bot/data/fetch_alpaca_daily.py SPY
```

To fetch a specific Alpaca range, pass an end date and duration:

```sh
mise exec -- uv run python src/trading_bot/data/fetch_alpaca_daily.py SPY --end-date 20250605 --duration "1 M"
```

To fetch backward from the oldest date already stored in `data/alpaca/daily/SPY.parquet`:

```sh
mise exec -- uv run python src/trading_bot/data/fetch_alpaca_daily.py SPY --end-date-from-parquet
```

`--end-date` and `--end-date-from-parquet` cannot be used together. If the symbol Parquet file does not exist or has no rows, `--end-date-from-parquet` uses today's US/Eastern date.

## Expected Output

The tool should first print the request range:

```text
Fetching SPY daily candles ending 2025-06-05 for duration 1 M via Alpaca API
```

If the request succeeds, it should print how many candles were fetched and where the merged Parquet file was written:

```text
Fetched 21 daily candles for SPY.
Wrote 21 total daily rows to data/alpaca/daily/SPY.parquet
```

Exact row counts depend on the requested date range and market calendar.

The tool should then write or update:

```text
data/alpaca/daily/SPY.parquet
```

If the Parquet file already exists, rows from the latest fetch are merged into it. The trading date is used as the row key, so a symbol file keeps only one row for each date.

## Common Issues

- Missing credentials: set `ALPACA_API_KEY` and `ALPACA_SECRET_KEY` or pass them with CLI flags.
- No historical bars: confirm the symbol, requested range, and Alpaca market data permissions.
- Authentication or entitlement errors: confirm the keys belong to the intended Alpaca account and data plan.
- Rate-limit errors: wait before retrying or reduce repeated requests.