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¶
- Python (ms-python.python) - Main Python extension
- Black Formatter (ms-python.black-formatter) - Python code formatter
- isort (ms-python.isort) - Python import organization
- Flake8 (ms-python.flake8) - Python linting
- Mypy Type Checker (ms-python.mypy-type-checker) - Python type checking
For Frontend Development¶
- ESLint (dbaeumer.vscode-eslint) - JavaScript/TypeScript linting
- Prettier (esbenp.prettier-vscode) - JavaScript/TypeScript formatting
Optional but Recommended¶
- Better Comments (aaron-bond.better-comments) - Color coded comment categorization
- GitLens (eamodio.gitlens) - Git capabilities in VS Code
- Docker (ms-azuretools.vscode-docker) - Docker integration
- 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¶
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¶
This applies Black's opinionated code formatting with a line length of 88 characters.
Automatic Import Organization on Save¶
This configuration automatically organizes your imports when you save Python files.
isort Configuration¶
The project includes an .isort.cfg
file with these settings:
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¶
- Clone the repository:
-
Install VS Code extensions:
-
Open VS Code
- Go to Extensions (Ctrl+Shift+X)
-
Search for and install all required extensions listed above
-
Open the project:
- File > Open Folder... > Select the fastapi_rbac directory
- 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:
-
Database fixtures:
-
Creates in-memory SQLite database for tests
- Creates test tables using SQLModel metadata
- Provides session fixtures for database access
-
Includes transaction isolation between tests
-
API Testing fixtures:
-
app
: Creates a FastAPI test application client
: HTTPx AsyncClient for making API requestssuperuser_token_headers
: Authentication headers for admin access-
normal_user_token_headers
: Authentication headers for regular user access -
Mock fixtures:
redis_mock
: AsyncMock for Redis operations- 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:
-
Unit Tests:
-
Test individual components in isolation
- Mock dependencies for focused testing
-
Fast execution for quick feedback
-
API Tests:
-
Test API endpoints through the FastAPI test client
- Verify correct responses and status codes
- Ensure proper error handling
-
Test authentication and authorization
-
CRUD Tests:
-
Test database operations
- Verify correct data persistence
-
Test constraints and relationships
-
Model Tests:
-
Verify model properties and methods
- Test model relationships
-
Validate data integrity constraints
-
Integration Tests:
- Test multiple components working together
- Focus on critical user workflows
- Verify system behavior end-to-end
Writing New Tests¶
When adding new features, follow these guidelines for writing tests:
- 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"
- 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"
- Test Setup Best Practices:
- Use fixtures for common setup
- Create helper functions for repeated test patterns
- Provide descriptive test names and docstrings
- Follow the AAA pattern (Arrange-Act-Assert)
- Clean up resources in teardown
Debugging Tests¶
When tests fail, you can debug using these techniques:
- Verbose Output:
- Print Statements: Add print statements to understand the state during test execution:
-
VS Code Debugger:
-
Set breakpoints in your test file
- Use the "Python: Debug Current File" command
-
Inspect variables in the debugger
-
Pytest Features:
- Use
pytest.set_trace()
for debugger - 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:
-
Formatting:
-
Black enforces consistent Python code style
-
Prettier enforces consistent JavaScript/TypeScript code style
-
Import Organization:
-
isort groups and sorts Python imports
-
ESLint organizes JavaScript/TypeScript imports
-
Linting:
-
Flake8 checks for Python code quality issues
-
ESLint checks for JavaScript/TypeScript code quality issues
-
Type Checking:
- Mypy enforces static type checking in Python
Troubleshooting¶
VS Code Doesn't Recognize Python Environment¶
- Open VS Code Command Palette (Ctrl+Shift+P)
- Select "Python: Select Interpreter"
- Choose the Python interpreter from your virtual environment
Import Sorting Not Working¶
- Check if isort extension is installed and enabled
- Ensure the virtual environment has isort installed
- Verify there are no errors in the VS Code Extensions panel
Black Formatting Not Working¶
- Check if Black extension is installed and enabled
- Ensure the virtual environment has Black installed
- Try running Black manually:
black <filename>
from terminal
Additional Information¶
For more information, refer to: