Skip to content

Development Guide

This guide covers development workflows, testing, and operational procedures for the SPOT Contracts repository.

Development Environment

Prerequisites

  • Docker and Docker Compose
  • Git
  • Make (for command shortcuts)

No local language dependencies required - Python, Node.js, and all tools run in Docker containers.

Initial Setup

# Clone repository
git clone https://codeberg.org/SPOT_Project/sdk.git
cd sdk

# Build development containers
make build

# Copy environment configuration
cp .env.example .env
# Edit .env with your GitLab settings

# Validate setup
make validate

Development Workflow

Standard Development Cycle

  1. Update OpenAPI specifications in openapi/ directory
  2. Validate changes: make validate
  3. Generate SDKs: make generate
  4. Run tests: make test
  5. Generate documentation: make docs
  6. Preview documentation: make docs-serve
  7. Commit and push changes

Adding New Services

  1. Create OpenAPI specification: 

    # Add new service specification
cp openapi/api-gateway.yaml openapi/new-service.yaml
# Edit openapi/new-service.yaml with service-specific schema

  2. Add Python interface models (optional): 

    # Create interface models in interfaces/
touch interfaces/new_service.py
# Define Pydantic models for service

  3. Validate and generate: 

    make validate
make generate

  4. Add tests: 

    # Create test file
touch tests/test_new_service.py
# Add comprehensive tests for new service
make test

  5. Update documentation: 

    make docs
make docs-serve  # Preview changes

Testing

Test Architecture

The repository uses comprehensive contract testing:

  • Location: tests/ directory
  • Framework: pytest with coverage reporting
  • Coverage Target: 97%+ code coverage
  • Docker-based: All tests run in containers

Running Tests

# Run all tests with coverage
make test

# Enter development shell for manual testing
make shell

# Run specific test file
docker compose run --rm dev pytest tests/test_analyzer.py -v

# Run tests with coverage report
docker compose run --rm dev pytest --cov=interfaces --cov-report=html

Test Structure

# Example test file: tests/test_analyzer.py
import pytest
from interfaces.analyzer import AnalysisResult, AnalysisIndicator

def test_analysis_result_creation():
    """Test creating a valid AnalysisResult."""
    result = AnalysisResult(
        is_phishing=True,
        threat_level="high",
        confidence=0.75,
        explanation="Found suspicious indicators",
        indicators=[],
        metadata=AnalysisMetadata(
            analyzer_id="test-analyzer",
            analyzer_version="1.0.0",
            analysis_duration_ms=100
        )
    )
    assert result.is_phishing == True
    assert result.threat_level == "high"
    assert result.confidence == 0.75

def test_analysis_result_validation():
    """Test AnalysisResult field validation."""
    with pytest.raises(ValueError):
        AnalysisResult(
            is_phishing=True,
            threat_level="invalid",  # Invalid threat level
            confidence=1.5,  # Invalid: must be 0.0-1.0
            explanation="test"
        )

Test Coverage

The test suite maintains high coverage across:

  • Interface Models: All Pydantic model validation
  • Generated SDKs: Basic functionality testing
  • OpenAPI Specs: Schema validation and structure
  • CI/CD Pipeline: End-to-end workflow testing

Docker Development

Container Architecture

# Development container includes:
FROM python:3.11-slim
# - Python 3.11 with Poetry
# - Node.js 18 with NPM
# - datamodel-code-generator (Python SDK generation)
# - openapi-typescript-codegen (TypeScript SDK generation)
# - pytest and coverage tools

Development Commands

# Build development environment
make build

# Enter interactive shell
make shell

# Run commands in container
docker compose run --rm dev python scripts/validate-specs.py
docker compose run --rm dev pytest tests/ -v
docker compose run --rm dev poetry install

CI/CD Pipeline

Pipeline Architecture

The GitLab CI/CD pipeline consists of three stages:

  1. validate:specs - OpenAPI specification validation
  2. test:contracts - Comprehensive contract tests (97%+ coverage)
  3. build - SDK generation, publishing, and documentation

Pipeline Configuration

stages:
  - validate
  - test
  - build

validate:specs:
  stage: validate
  script:
    - docker compose run --rm dev python scripts/validate-specs.py

test:contracts:
  stage: test
  script:
    - docker compose run --rm dev pytest --cov=interfaces --cov-report=xml
  coverage: '/TOTAL.+?(\d+\%)$/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

build:python:
  stage: build
  only:
    - tags
  variables:
    - /^python-v.*/
  script:
    - make generate
    - make publish-python

build:typescript:
  stage: build
  only:
    - tags
  variables:
    - /^typescript-v.*/
  script:
    - make generate
    - make publish-typescript

Automated Publishing

Trigger Action Registry
python-v1.0.0 tag Build & publish Python SDK GitLab PyPI Registry
typescript-v1.0.0 tag Build & publish TypeScript SDK GitLab NPM Registry
Main branch push Generate & deploy documentation GitLab Pages

Documentation System

Documentation Architecture

  • Source: Markdown files in docs/ directory
  • Generator: MkDocs with Material theme
  • API Docs: Swagger UI integration for OpenAPI specs
  • Hosting: GitLab Pages with auto-deployment

Documentation Commands

# Generate documentation site
make docs

# Serve documentation locally on port 8005
make docs-serve

# Clean documentation artifacts
rm -rf public temp_docs site

Adding Documentation

  1. Create markdown file in docs/ directory
  2. Update navigation in mkdocs.yml
  3. Generate and preview: make docs && make docs-serve
  4. Commit changes - documentation auto-deploys on main branch

Environment Configuration

Required Environment Variables

# GitLab Instance Configuration

CI_PROJECT_ID=303
GITLAB_TOKEN=glpat-your-token-here

# SSL Configuration (for private GitLab instances)
GITLAB_CA_CERT=certs/gitlab-ca.crt

# Docker Configuration
COMPOSE_PROJECT_NAME=spot-sdk

Best Practices

Code Quality

  • Always run make validate before committing
  • Maintain 95%+ test coverage
  • Use semantic versioning for SDK releases
  • Update documentation with new features

Git Workflow

  • Use feature branches for development
  • Write descriptive commit messages
  • Tag releases with proper format (python-v1.0.0, typescript-v1.0.0)
  • Keep main branch stable and deployable

OpenAPI Specifications

  • Follow OpenAPI 3.0 specification
  • Use descriptive schemas and examples
  • Validate specs before committing
  • Document all endpoints and models

Container Best Practices

  • Use specific image versions (not latest)
  • Minimize container layers
  • Run containers as non-root when possible
  • Use multi-stage builds for production images

Troubleshooting

Common Issues

OpenAPI Validation Fails

# Check specific validation errors
make validate
docker compose run --rm dev python scripts/validate-specs.py

SDK Generation Fails

# Check Docker container status
docker compose ps
docker compose logs dev

# Rebuild containers
make build

Tests Failing

# Run tests with verbose output
docker compose run --rm dev pytest tests/ -v -s

# Check coverage report
docker compose run --rm dev pytest --cov=interfaces --cov-report=html

Publishing Errors

# Check environment configuration
make check-versions

# Verify GitLab token permissions
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "$GITLAB_URL/api/v4/user"

Getting Help

SDK Resources:

Platform Integration:

When testing your analyzer with the SPOT Platform: