---
title: "Test Instructions: Network Executor and iModel Refactor"
by: "@khive-implementer"
created: 2025-05-20
updated: 2025-05-20
version: 1.0
doc_type: TI
output_subdir: ti
description: >
  Test instructions for the new lionfuncs.network.executor.Executor class,
  the NetworkRequestEvent, and the iModel implementation.
date: 2025-05-20
author: "@khive-implementer"
status: "Draft"
issue_url: "https://github.com/khive-ai/lionfuncs/issues/17"
research_report_url: ".khive/reports/rr/RR-17.md"
technical_design_url: ".khive/reports/tds/TDS-17.md"
implementation_plan_url: ".khive/reports/ip/IP-17.md"
---

# Test Instructions: Network Executor and iModel Refactor

## 1. Overview

This document provides instructions for testing the implementation of Issue #17,
which includes:

1. The `NetworkRequestEvent` class in `src/lionfuncs/network/events.py`
2. The `Executor` class in `src/lionfuncs/network/executor.py`
3. The `iModel` class in `src/lionfuncs/network/imodel.py`

## 2. Test Environment Setup

### 2.1. Prerequisites

- Python 3.10 or higher
- `uv` package manager

### 2.2. Setup Steps

1. Clone the repository (if not already done):
   ```bash
   git clone https://github.com/khive-ai/lionfuncs.git
   cd lionfuncs
   ```

2. Create a feature branch:
   ```bash
   git checkout -b feature/17-network-executor
   ```

3. Initialize the development environment:
   ```bash
   khive init
   ```

## 3. Running the Tests

### 3.1. Run All Tests

To run all tests for the project:

```bash
uv run pytest tests
```

### 3.2. Run Specific Tests

To run only the tests for the new components:

```bash
uv run pytest tests/unit/network/test_events.py tests/unit/network/test_executor.py tests/unit/network/test_imodel.py
```

### 3.3. Run with Coverage

To run tests with coverage reporting:

```bash
uv run pytest tests/unit/network/test_events.py tests/unit/network/test_executor.py tests/unit/network/test_imodel.py --cov=src/lionfuncs/network/events.py --cov=src/lionfuncs/network/executor.py --cov=src/lionfuncs/network/imodel.py --cov-report=term-missing
```

## 4. Test Cases

### 4.1. NetworkRequestEvent Tests

The `test_events.py` file contains tests for the `NetworkRequestEvent` class:

- Test initialization with default and custom values
- Test status updates and timestamp tracking
- Test result setting and status transition to COMPLETED
- Test error setting and status transition to FAILED
- Test log addition

### 4.2. Executor Tests

The `test_executor.py` file contains tests for the `Executor` class:

- Test initialization with default and custom values
- Test start and stop methods
- Test task submission and processing
- Test concurrency limiting
- Test request rate limiting
- Test API token rate limiting
- Test error handling
- Test context manager usage

### 4.3. iModel Tests

The `test_imodel.py` file contains tests for the `iModel` class:

- Test initialization with Executor and configuration
- Test API call methods
- Test integration with Executor
- Test error handling
- Test context manager usage

## 5. Manual Testing

### 5.1. Basic Functionality Test

1. Create a simple script that uses the `Executor` and `iModel` classes to make
   API calls to a public API (e.g., JSONPlaceholder).
2. Verify that rate limiting is applied correctly.
3. Verify that concurrency limiting is applied correctly.
4. Verify that API token limiting is applied correctly (if applicable).

### 5.2. Error Handling Test

1. Create a script that intentionally causes errors during API calls.
2. Verify that errors are properly captured in the `NetworkRequestEvent`.
3. Verify that the `Executor` continues processing other tasks after an error.

## 6. Verification Checklist

Use this checklist to verify that the implementation meets the requirements:

- [ ] `NetworkRequestEvent` class is implemented according to the TDS
- [ ] `Executor` class is implemented according to the TDS
- [ ] `iModel` class is implemented according to the TDS
- [ ] All tests pass
- [ ] Code coverage is >80%
- [ ] Code passes linting and formatting checks
- [ ] Documentation is complete and accurate

## 7. Troubleshooting

### 7.1. Common Issues

- **Issue**: Tests fail with asyncio-related errors. **Solution**: Ensure that
  tests are properly using asyncio fixtures and that event loops are properly
  managed.

- **Issue**: Rate limiting tests are flaky. **Solution**: Use controlled time
  advancement rather than real time for testing rate limiting behavior.

- **Issue**: Mock objects are not behaving as expected. **Solution**: Verify
  that mock objects are properly configured and that the code under test is
  interacting with them as expected.

### 7.2. Debugging Tips

- Use `pytest -v` for more verbose output.
- Use `pytest --pdb` to drop into the debugger on test failures.
- Add logging statements to the code to track execution flow.
- Use `asyncio.create_task` with names to help identify tasks in logs.

## 8. Conclusion

Following these test instructions will help ensure that the implementation of
the `NetworkRequestEvent`, `Executor`, and `iModel` classes meets the
requirements specified in the Technical Design Specification and functions
correctly in various scenarios.
