Developer Setup Guide

This guide provides detailed instructions for setting up the development environment for the FastAPI RBAC project. It includes instructions for configuring your IDE, installing dependencies, and common workflows.

VS Code Setup

This project uses Visual Studio Code for development with a standardized set of extensions and configurations to maintain code quality and consistency across the team.

Required Extensions

Install the following extensions for the optimal development experience:

For Python Development

1. Python (ms-python.python) - Main Python extension
2. Black Formatter (ms-python.black-formatter) - Python code formatter
3. isort (ms-python.isort) - Python import organization
4. Flake8 (ms-python.flake8) - Python linting
5. Mypy Type Checker (ms-python.mypy-type-checker) - Python type checking

For Frontend Development

1. ESLint (dbaeumer.vscode-eslint) - JavaScript/TypeScript linting
2. Prettier (esbenp.prettier-vscode) - JavaScript/TypeScript formatting

Optional but Recommended

1. Better Comments (aaron-bond.better-comments) - Color coded comment categorization
2. GitLens (eamodio.gitlens) - Git capabilities in VS Code
3. Docker (ms-azuretools.vscode-docker) - Docker integration
4. REST Client (humao.rest-client) - Test API endpoints directly from VS Code

Workspace Settings

The project includes workspace settings at .vscode/settings.json with configurations for:

Import Sorting with isort

"isort.args": ["--profile", "black"]

This configures isort to follow Black's code style, which:

• Places imports on separate lines
• Groups imports by standard library, third-party, and local
• Sorts alphabetically within groups

Python Code Formatting with Black

"black-formatter.args": ["--line-length", "88"]

This applies Black's opinionated code formatting with a line length of 88 characters.

Automatic Import Organization on Save

"[python]": {
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  }
}

This configuration automatically organizes your imports when you save Python files.

isort Configuration

The project includes an .isort.cfg file with these settings:

[settings]
profile=black
multi_line_output=3
line_length=88

This configuration:

• Makes isort compatible with Black's formatting style
• Sets multi-line output format to vertical hanging indent
• Aligns line length with Black's settings

Setup Instructions

First-Time Setup

1. Clone the repository:

git clone <repository-url>
cd fastapi_rbac

1. Install VS Code extensions:

2. Open VS Code

3. Go to Extensions (Ctrl+Shift+X)

4. Search for and install all required extensions listed above

5. Open the project:

6. File > Open Folder... > Select the fastapi_rbac directory
7. The workspace settings will automatically apply

Backend Setup

Follow the backend setup instructions in the main README.md to set up your Python environment and dependencies.

Frontend Setup

Follow the frontend setup instructions in the main README.md to set up your Node.js environment and dependencies.

Testing Framework

Test Structure

The project uses pytest for testing with the following structure:

backend/test/
├── conftest.py                    # Test configuration and fixtures
├── test_config.py                 # Configuration for test environment
├── utils.py                       # Utility functions for tests
├── test_api_*.py                  # API endpoint tests
├── test_crud_*.py                 # CRUD operation tests
├── test_models_*.py               # Database model tests
└── test_integration_*.py          # Integration tests

Test Configuration

Tests are configured in conftest.py which provides:

1. Database fixtures:

2. Creates in-memory SQLite database for tests

3. Creates test tables using SQLModel metadata
4. Provides session fixtures for database access

5. Includes transaction isolation between tests

6. API Testing fixtures:

7. app: Creates a FastAPI test application

8. client: HTTPx AsyncClient for making API requests
9. superuser_token_headers: Authentication headers for admin access

10. normal_user_token_headers: Authentication headers for regular user access

11. Mock fixtures:

12. redis_mock: AsyncMock for Redis operations
13. Various service mocks for external dependencies

Running Tests

You can run tests using the provided script:

# Run all tests
cd backend
python run_tests.py

# Run specific test file
python run_tests.py test/test_api_auth.py

# Run specific test function
python run_tests.py test/test_api_auth.py::test_login_successful

# Run tests with verbose output
python run_tests.py --verbose

# Run tests with coverage report
python run_tests.py --coverage

Testing Strategy

The project follows these testing principles:

1. Unit Tests:

2. Test individual components in isolation

3. Mock dependencies for focused testing

4. Fast execution for quick feedback

5. API Tests:

6. Test API endpoints through the FastAPI test client

7. Verify correct responses and status codes
8. Ensure proper error handling

9. Test authentication and authorization

10. CRUD Tests:

11. Test database operations

12. Verify correct data persistence

13. Test constraints and relationships

14. Model Tests:

15. Verify model properties and methods

16. Test model relationships

17. Validate data integrity constraints

18. Integration Tests:

19. Test multiple components working together
20. Focus on critical user workflows
21. Verify system behavior end-to-end

Writing New Tests

When adding new features, follow these guidelines for writing tests:

1. API Endpoint Tests:

@pytest.mark.asyncio
async def test_new_endpoint(client: AsyncClient, superuser_token_headers: Dict[str, str]) -> None:
    """Test description here"""
    # Arrange - prepare test data
    test_data = {"field1": "value1", "field2": "value2"}

    # Act - make API request
    response = await client.post(
        f"{settings.API_V1_STR}/your-endpoint",
        json=test_data,
        headers=superuser_token_headers
    )

    # Assert - verify response
    assert response.status_code == 201
    result = response.json()
    assert result["status"] == "success"
    assert "field1" in result["data"]
    assert result["data"]["field1"] == "value1"

1. CRUD Tests:

@pytest.mark.asyncio
async def test_crud_operation(db: AsyncSession) -> None:
    """Test description here"""
    # Arrange - prepare test data
    obj_in = IYourModelCreate(field1="value1", field2="value2")

    # Act - perform CRUD operation
    obj = await crud.your_model.create(db_session=db, obj_in=obj_in)

    # Assert - verify result
    assert obj.field1 == "value1"
    assert obj.field2 == "value2"

1. Test Setup Best Practices:
2. Use fixtures for common setup
3. Create helper functions for repeated test patterns
4. Provide descriptive test names and docstrings
5. Follow the AAA pattern (Arrange-Act-Assert)
6. Clean up resources in teardown

Debugging Tests

When tests fail, you can debug using these techniques:

1. Verbose Output:

python run_tests.py test/failing_test.py -v

1. Print Statements: Add print statements to understand the state during test execution:

print(f"Response: {response.json()}")

1. VS Code Debugger:

2. Set breakpoints in your test file

3. Use the "Python: Debug Current File" command

4. Inspect variables in the debugger

5. Pytest Features:

6. Use pytest.set_trace() for debugger
7. Use -s flag to see print outputs

Continuous Integration

The project uses GitHub Actions for continuous integration, which runs:

• Linting checks
• Type checking
• Unit tests
• Integration tests

The CI workflow is defined in .github/workflows/ci.yml and .github/workflows/test.yml.

Code Quality Guidelines

The configured tools enforce these guidelines automatically:

1. Formatting:

2. Black enforces consistent Python code style

3. Prettier enforces consistent JavaScript/TypeScript code style

4. Import Organization:

5. isort groups and sorts Python imports

6. ESLint organizes JavaScript/TypeScript imports

7. Linting:

8. Flake8 checks for Python code quality issues

9. ESLint checks for JavaScript/TypeScript code quality issues

10. Type Checking:

11. Mypy enforces static type checking in Python

Troubleshooting

VS Code Doesn't Recognize Python Environment

1. Open VS Code Command Palette (Ctrl+Shift+P)
2. Select "Python: Select Interpreter"
3. Choose the Python interpreter from your virtual environment

Import Sorting Not Working

1. Check if isort extension is installed and enabled
2. Ensure the virtual environment has isort installed
3. Verify there are no errors in the VS Code Extensions panel

Black Formatting Not Working

1. Check if Black extension is installed and enabled
2. Ensure the virtual environment has Black installed
3. Try running Black manually: black <filename> from terminal

Additional Information

For more information, refer to:

• Python Extension for VS Code
• Black documentation
• isort documentation
• Flake8 documentation
• Mypy documentation
• Pytest documentation
• FastAPI testing
• SQLModel testing