# HTTP Test Server Fixture

The HTTP test server fixture provides a way to test conda functionality that requires serving files over HTTP, such as:

- Mock conda channels with packages
- Remote environment files (`environment.yml`)
- Remote configuration files
- Any scenario where conda needs to fetch files from a URL

## Overview

The `http_test_server` fixture starts a local HTTP server that serves files from a directory. The server runs on a random port and supports both IPv4 and IPv6.

The fixture can be used in two ways:

1. **Without `@pytest.mark.parametrize`** - Use a temporary directory that you populate dynamically
2. **With `@pytest.mark.parametrize`** - Serve files from a pre-existing directory

```{tip}
For proper type hints, import `HttpTestServerFixture` from `conda.testing.fixtures` under `TYPE_CHECKING`.
See the [complete example](#complete-example-testing-a-mock-channel) for the full import pattern.
```

## Basic Usage

### Dynamic Content (No Marker)

The simplest usage - no marker needed. The server automatically uses a temporary directory that you can populate:

```python
def test_dynamic_repodata(http_test_server: HttpTestServerFixture):
    """Create content on the fly - no setup needed."""
    # Populate files directly in the server's directory
    (http_test_server.directory / "repodata.json").write_text('{"packages": {}}')

    # Make request
    response = requests.get(http_test_server.get_url("repodata.json"))
    assert response.status_code == 200
    assert response.json() == {"packages": {}}
```

This pattern is ideal for:

- Creating mock repodata files
- Testing with minimal setup
- Extending and creating your own fixtures programmatically

### Pre-existing Directory (With Parametrize)

Use `@pytest.mark.parametrize()` with `indirect=True` when you have test data already prepared:

```python
@pytest.mark.parametrize(
    "http_test_server",
    ["tests/data/mock-channel"],
    indirect=True,
)
def test_fetch_from_channel(http_test_server: HttpTestServerFixture):
    # Server serves files from tests/data/mock-channel/
    repodata_url = http_test_server.get_url("linux-64/repodata.json")

    response = requests.get(repodata_url)
    assert response.status_code == 200
```

The `indirect=True` parameter tells pytest to pass the directory path to the fixture rather than directly to the test function.

This pattern is ideal for:

- Complex directory structures
- Sharing test data across multiple tests
- Binary files (packages, archives)
- Large test datasets

## Testing Multiple Directories

One of the benefits of using `@pytest.mark.parametrize` is that you can easily test the same logic against multiple directories:

```python
@pytest.mark.parametrize(
    "http_test_server",
    [
        "tests/data/channel1",
        "tests/data/channel2",
        "tests/data/channel3",
    ],
    indirect=True,
)
def test_multiple_channels(http_test_server: HttpTestServerFixture):
    # This test runs three times, once for each channel directory
    response = requests.get(http_test_server.get_url("repodata.json"))
    assert response.status_code == 200
    assert "packages" in response.json()
```

Each test run will use a different directory, making it easy to verify behavior across multiple datasets.

You can also mix pre-existing directories with dynamic content by using `None`:

```python
@pytest.mark.parametrize(
    "http_test_server",
    [
        "tests/data/channel1",
        None,
        "tests/data/channel2",
    ],
    indirect=True,
)
def test_mixed_sources(http_test_server: HttpTestServerFixture):
    # Runs 3 times: channel1, dynamic tmp dir, channel2
    # When None, http_test_server.directory is a fresh temporary directory
    ...
```

## Complete Example: Testing a Mock Channel

Here's a full example with all imports showing dynamic content generation:

```python
from __future__ import annotations

import json
from pathlib import Path
from typing import TYPE_CHECKING

import pytest
import requests

if TYPE_CHECKING:
    from conda.testing.fixtures import CondaCLIFixture, HttpTestServerFixture


def test_install_from_mock_channel(
    http_test_server: HttpTestServerFixture,
    conda_cli: CondaCLIFixture,
    tmp_path: Path,
):
    """Test installing from a dynamically created mock channel."""
    # Create channel structure on the fly
    noarch = http_test_server.directory / "noarch"
    noarch.mkdir()

    # Create minimal repodata
    repodata = {"packages": {}, "packages.conda": {}, "repodata_version": 1}
    (noarch / "repodata.json").write_text(json.dumps(repodata))

    # Use the channel
    channel_url = http_test_server.url
    stdout, stderr, code = conda_cli(
        "search",
        f"--channel={channel_url}",
        "--override-channels",
        "*",
    )

    # Verify it worked (no packages found but channel was accessible)
    assert code == 0


@pytest.mark.parametrize(
    "http_test_server",
    ["tests/data/mock-channel"],
    # Assume the following structure:
    # tests/data/mock-channel/
    #   ├── noarch/
    #   │   └── repodata.json
    #   └── linux-64/
    #       ├── repodata.json
    #       └── example-pkg-1.0.0-0.tar.bz2
    indirect=True,
)
def test_install_from_preexisting_channel(
    http_test_server: HttpTestServerFixture,
    conda_cli: CondaCLIFixture,
    tmp_path: Path,
):
    """Test installing from pre-existing mock channel."""
    channel_url = http_test_server.url

    stdout, stderr, code = conda_cli(
        "create",
        f"--prefix={tmp_path}",
        f"--channel={channel_url}",
        "example-pkg",
        "--yes",
    )

    assert code == 0
    assert (tmp_path / "conda-meta" / "example-pkg-1.0.0-0.json").exists()
```

## Fixture API Reference

### HttpTestServerFixture

The fixture returns an instance with these attributes and methods:

#### Attributes:

- `server: http.server.ThreadingHTTPServer` - The underlying server instance
- `host: str` - Server host (usually `127.0.0.1`)
- `port: int` - Server port (random)
- `url: str` - Base URL (e.g., `http://127.0.0.1:54321`)
- `directory: Path` - The directory being served (writable, use to populate content)

#### Methods:

- `get_url(path: str = "") -> str` - Get full URL for a path
  - Example: `get_url("linux-64/repodata.json")` → `"http://127.0.0.1:54321/linux-64/repodata.json"`

#### Using the `directory` attribute:

```python
def test_dynamic_files(http_test_server: HttpTestServerFixture):
    # Write files directly to the served directory
    (http_test_server.directory / "file.txt").write_text("content")

    # Create subdirectories
    subdir = http_test_server.directory / "subdir"
    subdir.mkdir()
    (subdir / "nested.json").write_text('{"key": "value"}')

    # Files are immediately accessible via HTTP
    response = requests.get(http_test_server.get_url("subdir/nested.json"))
    assert response.json() == {"key": "value"}
```

## Use in Downstream Projects

The HTTP test server fixture is part of the `conda.testing` module and can be used by downstream projects:

```python
# In your project's conftest.py
pytest_plugins = "conda.testing.fixtures"
```

Then use it in your tests:

```python
@pytest.mark.parametrize("http_test_server", ["tests/my-mock-channel"], indirect=True)
def test_with_mock_channel(http_test_server: HttpTestServerFixture):
    channel_url = http_test_server.url
    # ... your test code ...
```

## Troubleshooting

### "ValueError: Directory does not exist"

- This error occurs when using `@pytest.mark.parametrize()` with an invalid path
- Check that the directory path provided in parametrize exists
- Use absolute paths or paths relative to the repository root
- Use `Path(__file__).parent / "data"` if needed
- Or omit the parametrize decorator entirely to use a temporary directory

### "ValueError: Path is not a directory"

- This error occurs when the parametrize value points to a file instead of a directory
- Ensure the path in `@pytest.mark.parametrize(..., indirect=True)` points to a directory
- Or use the fixture without parametrize for dynamic content

### Address already in use

- The fixture uses random ports, so this is rare
- If it happens, the test will likely fail and retry automatically

### Server not shutting down cleanly

- This is handled automatically by the fixture
- The server runs on a daemon thread and will be cleaned up when tests finish

### Files not appearing in HTTP responses

- Make sure files are written before making the HTTP request
- Check that file paths don't have leading slashes when using `get_url()`
- Verify the directory structure with `list(http_test_server.directory.iterdir())`

## Tips and Best Practices

1. **Prefer dynamic content**: Use the fixture without parametrize (dynamic content) for simple use cases. It's simpler and doesn't require maintaining test data files.

2. **Use parametrize for complex data**: Use `@pytest.mark.parametrize(..., indirect=True)` when you have complex directory structures, binary files, or data shared across many tests.

3. **Function scope for isolation**: Each test gets its own temporary directory with the `http_test_server` fixture (function scope), providing complete isolation.

4. **Organize test data**: When using parametrize, keep mock channel data in dedicated directories like `tests/data/mock-channels/` with README files explaining the structure.

5. **Test error scenarios**: Use dynamic content to easily test edge cases like malformed repodata, missing packages, or network timeouts.

6. **Cleanup is automatic**: The fixture handles cleanup automatically - no need to manually shut down servers or delete temporary files.

## Examples from conda Test Suite

See these files for real-world usage examples:

- `tests/testing/test_http_test_server.py` - Tests for the fixture itself
- `tests/env/test_create.py::test_create_update_remote_env_file` - Using remote environment files
- `tests/gateways/test_connection.py` - Connection and download testing