Forem: JEFFERSON ROSAS CHAMBILLA

Spec Driven Development: Build Software That Actually Does What You Promised

JEFFERSON ROSAS CHAMBILLA — Wed, 29 Apr 2026 23:04:17 +0000

Spec Driven Development: Build Software That Actually Does What You Promised

"A well-written specification is not a constraint on creativity — it's a contract that frees everyone to move fast with confidence."

The Problem We've All Lived

You've been there. A sprint ends, the feature ships, and someone from the QA team — or worse, the client — asks: "Wait, but what happens when the user submits a negative amount? What if the email is missing?"

Silence. Awkward GitHub blame. A hotfix at 11pm.

The root cause is almost never bad code. It's a missing or ambiguous specification. The developer built something — just not the right something, because no one clearly defined what "right" looked like before a single line was written.

This is the problem Spec Driven Development (SDD) solves.

What Is Spec Driven Development?

Spec Driven Development is a software methodology where a formal, machine-readable (or at minimum, unambiguous human-readable) specification is written and agreed upon before any implementation begins.

The spec becomes the single source of truth for:

What inputs are valid
What outputs are expected
What edge cases must be handled
What errors should be raised and when

Unlike TDD (Test Driven Development), which starts from test cases, SDD starts one layer above — from a contract between all stakeholders. Tests are then derived from the spec, not invented alongside the code.

SDD vs. Other Methodologies

	TDD	BDD	SDD
Starts with	Test cases	User behavior scenarios	Formal specification
Written by	Developers	Devs + QA + PO	All stakeholders
Primary artifact	Test file	`.feature` file	Spec document / schema
Code follows	The tests	The scenarios	The spec
Catches	Regressions	Behavior gaps	Contract violations

SDD doesn't replace TDD or BDD — it precedes them. Once your spec exists, you can generate tests from it automatically.

Core Principles of SDD

1. 🔏 The Spec Is Law

No behavior is implemented without being in the spec. No spec item goes unimplemented. The spec and the code stay in sync — if the spec changes, the code changes, and vice versa.

2. 📐 Precision Over Prose

Specs written in vague English ("the system should handle errors gracefully") are useless. Good specs define exactly what "gracefully" means: which HTTP status code, which error payload shape, which log level.

3. 🤝 Shared Ownership

The spec is co-authored. Developers, product managers, QA engineers, and sometimes clients all sign off. This eliminates the "that's not what I meant" conversation after delivery.

4. 🔄 Living Document

Specs evolve. But every change goes through a deliberate revision process — not a Slack message at 4pm asking to "quickly tweak something."

Real-World Example: A Payment Processing Module

Let's walk through SDD end-to-end using a concrete scenario.

📋 The Business Request

"We need a charge endpoint. It should take a user's card and amount, and process a payment."

Classic. Now watch how SDD transforms this vague request into airtight software.

Step 1: Write the Spec

Before touching an IDE, the team drafts the specification. We'll use OpenAPI 3.0 format — widely adopted, tooling-rich, and human-readable.

# payment-spec.yaml
openapi: 3.0.3
info:
  title: Payment Processing API
  version: 1.0.0

paths:
  /payments/charge:
    post:
      summary: Charge a payment method
      operationId: chargePayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeRequest'
      responses:
        '200':
          description: Payment successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment declined by provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error

components:
  schemas:
    ChargeRequest:
      type: object
      required: [amount, currency, card_token, idempotency_key]
      properties:
        amount:
          type: integer
          minimum: 50          # Minimum charge: $0.50 (in cents)
          maximum: 99999999    # Maximum charge: $999,999.99
          description: Amount in the smallest currency unit (e.g., cents for USD)
        currency:
          type: string
          enum: [USD, EUR, PEN, GBP]
          description: ISO 4217 currency code
        card_token:
          type: string
          pattern: '^tok_[a-zA-Z0-9]{24}$'
          description: Tokenized card reference from the frontend SDK
        idempotency_key:
          type: string
          minLength: 16
          maxLength: 64
          description: Client-generated unique key to prevent duplicate charges
        description:
          type: string
          maxLength: 255
          description: Optional human-readable description for the charge

    ChargeResponse:
      type: object
      required: [charge_id, status, amount, currency, created_at]
      properties:
        charge_id:
          type: string
          description: Unique identifier for this charge
        status:
          type: string
          enum: [succeeded, pending]
        amount:
          type: integer
        currency:
          type: string
        created_at:
          type: string
          format: date-time

    ErrorResponse:
      type: object
      required: [error_code, message]
      properties:
        error_code:
          type: string
          enum:
            - INVALID_AMOUNT
            - INVALID_CURRENCY
            - INVALID_CARD_TOKEN
            - CARD_DECLINED
            - INSUFFICIENT_FUNDS
            - DUPLICATE_IDEMPOTENCY_KEY
            - INTERNAL_ERROR
        message:
          type: string
        details:
          type: object

Notice what just happened. In ~90 lines of YAML, we have answered:

✅ What fields are required vs. optional?
✅ What are the valid currencies?
✅ What's the minimum and maximum charge?
✅ What does the card token format look like?
✅ What exact error codes exist, and when?
✅ What does a success response look like?

Zero ambiguity. Every stakeholder reviews and signs off on this before Sprint 1 starts.

Step 2: Generate Validation From the Spec

With a spec in place, we don't write validation logic by hand — we generate it. Tools like ajv, zod, or fastify's built-in schema support can consume OpenAPI schemas directly.

// src/schemas/chargeSchema.ts
import { z } from 'zod';

// This mirrors our OpenAPI spec exactly — one source of truth
export const ChargeRequestSchema = z.object({
  amount: z
    .number()
    .int()
    .min(50, 'Amount must be at least 50 cents')
    .max(99_999_999, 'Amount exceeds maximum allowed'),
  currency: z.enum(['USD', 'EUR', 'PEN', 'GBP']),
  card_token: z
    .string()
    .regex(/^tok_[a-zA-Z0-9]{24}$/, 'Invalid card token format'),
  idempotency_key: z.string().min(16).max(64),
  description: z.string().max(255).optional(),
});

export type ChargeRequest = z.infer<typeof ChargeRequestSchema>;

Step 3: Implement Against the Contract

Now developers write the controller. The spec is their guide — they're not making design decisions on the fly.

// src/controllers/paymentController.ts
import { Request, Response } from 'express';
import { ChargeRequestSchema } from '../schemas/chargeSchema';
import { PaymentService } from '../services/paymentService';
import { IdempotencyService } from '../services/idempotencyService';

export async function chargePayment(req: Request, res: Response) {
  // Step 1: Validate against spec
  const parsed = ChargeRequestSchema.safeParse(req.body);

  if (!parsed.success) {
    return res.status(400).json({
      error_code: 'INVALID_AMOUNT', // Derive from Zod issues
      message: parsed.error.errors[0].message,
      details: parsed.error.flatten(),
    });
  }

  const { amount, currency, card_token, idempotency_key, description } = parsed.data;

  // Step 2: Check idempotency (spec requires this)
  const existing = await IdempotencyService.find(idempotency_key);
  if (existing) {
    // Spec says: return the original response, not an error
    return res.status(200).json(existing.response);
  }

  // Step 3: Process payment
  try {
    const charge = await PaymentService.charge({
      amount,
      currency,
      cardToken: card_token,
      description,
    });

    const response = {
      charge_id: charge.id,
      status: charge.status,  // 'succeeded' | 'pending' — per spec
      amount,
      currency,
      created_at: charge.createdAt.toISOString(),
    };

    // Store for idempotency
    await IdempotencyService.store(idempotency_key, response);

    return res.status(200).json(response);

  } catch (err: any) {
    if (err.code === 'card_declined') {
      return res.status(402).json({
        error_code: 'CARD_DECLINED',
        message: 'Your card was declined. Please try a different payment method.',
      });
    }

    if (err.code === 'insufficient_funds') {
      return res.status(402).json({
        error_code: 'INSUFFICIENT_FUNDS',
        message: 'Insufficient funds on the card.',
      });
    }

    return res.status(500).json({
      error_code: 'INTERNAL_ERROR',
      message: 'An unexpected error occurred.',
    });
  }
}

Every error_code in the catch blocks maps directly to the spec's ErrorResponse.error_code enum. If a developer tries to return 'CARD_FAILED' instead of 'CARD_DECLINED', the TypeScript types — derived from the spec — will reject it at compile time.

Step 4: Tests Are Derived From the Spec

The spec enumerates every case. Tests write themselves.

// src/__tests__/chargePayment.spec.ts
import request from 'supertest';
import { app } from '../app';

describe('POST /payments/charge — Spec Compliance', () => {
  const validPayload = {
    amount: 2500,
    currency: 'USD',
    card_token: 'tok_A1B2C3D4E5F6G7H8I9J0K1L2',
    idempotency_key: 'idem_test_key_12345678',
  };

  // ✅ Spec: 200 on valid charge
  it('returns 200 with charge_id and status on success', async () => {
    const res = await request(app).post('/payments/charge').send(validPayload);
    expect(res.status).toBe(200);
    expect(res.body).toMatchObject({
      charge_id: expect.any(String),
      status: expect.stringMatching(/^(succeeded|pending)$/),
      amount: 2500,
      currency: 'USD',
    });
  });

  // ❌ Spec: 400 when amount < 50
  it('returns 400 when amount is below minimum (50)', async () => {
    const res = await request(app)
      .post('/payments/charge')
      .send({ ...validPayload, amount: 10 });
    expect(res.status).toBe(400);
    expect(res.body.error_code).toBe('INVALID_AMOUNT');
  });

  // ❌ Spec: 400 for unsupported currency
  it('returns 400 for unsupported currency', async () => {
    const res = await request(app)
      .post('/payments/charge')
      .send({ ...validPayload, currency: 'JPY' });
    expect(res.status).toBe(400);
  });

  // ❌ Spec: 400 for malformed card_token
  it('returns 400 for malformed card token', async () => {
    const res = await request(app)
      .post('/payments/charge')
      .send({ ...validPayload, card_token: 'invalid-token' });
    expect(res.status).toBe(400);
  });

  // 🔁 Spec: idempotency — same key returns same response
  it('returns same response for duplicate idempotency_key', async () => {
    const first = await request(app).post('/payments/charge').send(validPayload);
    const second = await request(app).post('/payments/charge').send(validPayload);
    expect(second.status).toBe(200);
    expect(second.body.charge_id).toBe(first.body.charge_id);
  });

  // 💳 Spec: 402 on card decline
  it('returns 402 with CARD_DECLINED when provider declines', async () => {
    const res = await request(app)
      .post('/payments/charge')
      .send({ ...validPayload, card_token: 'tok_declineSimulator000000000' });
    expect(res.status).toBe(402);
    expect(res.body.error_code).toBe('CARD_DECLINED');
  });
});

Every test maps to a spec statement. Code review becomes easy: "Does this test correspond to a spec requirement? Does every spec requirement have a test?"

The Payoff: What SDD Actually Gives You

🚀 Faster Onboarding

New developers read the spec and immediately understand what the system does — without reading implementation code.

🧪 Automatic Test Coverage Guidance

The spec is a checklist. If a spec item has no test, your coverage is incomplete. No guessing.

🤝 Fewer Miscommunications

When a PM asks "does it handle duplicate submissions?", you point to the spec: idempotency_key — yes, it does, here's exactly how.

🔒 Contract Stability

Frontend and backend teams can work in parallel. The API contract is defined. The frontend mocks from the spec; the backend implements against the spec. Integration becomes trivial.

📦 Tooling Bonuses

From a single OpenAPI spec you can auto-generate:

SDK client code (TypeScript, Python, Go...)
Interactive API documentation (Swagger UI, Redoc)
Mock servers for frontend development
Postman collections
Load test configurations

Common Pitfalls to Avoid

❌ Writing the spec after the code
This defeats the purpose. The spec becomes documentation, not a contract.

❌ Over-specifying implementation details
The spec defines what, not how. Don't put database queries or internal algorithms in the spec.

❌ Letting the spec drift from the code
Treat spec changes like code changes: pull requests, reviews, version tags. A stale spec is worse than no spec.

❌ Only developers writing the spec
If QA and product haven't reviewed it, edge cases will be missed. SDD is a team sport.

Tools to Get Started

Tool	Purpose
OpenAPI / Swagger	API specification format
Zod	TypeScript-first schema validation
Prism	Mock server from OpenAPI spec
Dredd	Test API against its spec automatically
Spectral	OpenAPI linting
oapi-codegen	Go code generation from OpenAPI
openapi-typescript	TypeScript types from OpenAPI

Conclusion

Spec Driven Development shifts the conversation from "we'll figure it out as we build" to "we've agreed on the contract, now let's build." It's not bureaucracy — it's engineering discipline that saves you from the 11pm hotfix, the post-launch confusion, and the eternal question of whose fault the bug was.

The payment module we built today had zero ambiguity from day one:

Every error code was named before a single catch block was written
The idempotency requirement was specified before anyone thought to implement it
The frontend team could mock the API on day one

That's the power of writing the spec first.

What about you — do you use any spec-first approaches in your team? Have you tried OpenAPI or GraphQL SDL as a contract? Let me know in the comments 👇

#softwaredevelopment #api #webdev #typescript #bestpractices

Math & Calculator MCP Server

JEFFERSON ROSAS CHAMBILLA — Thu, 04 Dec 2025 14:59:32 +0000

A powerful Model Context Protocol (MCP) Server that provides advanced mathematical utilities and calculator tools for AI assistants like Claude and other MCP-compatible clients.

📖 About

This MCP server exposes mathematical tools that AI assistants can use to perform calculations, statistical analysis, unit conversions, and more. Built with the Model Context Protocol SDK, it seamlessly integrates with Claude Desktop, VSCode, and other MCP clients.

Author: Jefferson Rosas Chambilla

Repository: https://github.com/Ankluna72/Math-Calculator-MCP-Server-

✨ Features

🔢 Basic Calculator

Addition, subtraction, multiplication, division
Power, square root, modulo operations
Error handling (division by zero, invalid operations)

📊 Statistical Analysis

Mean, median, mode
Standard deviation and variance
Complete statistical summaries

🔄 Unit Conversions

Length: meters, kilometers, miles, feet, inches
Weight: kilograms, grams, pounds, ounces
Temperature: Celsius, Fahrenheit, Kelvin

📐 Equation Solver

Quadratic equation solver (ax² + bx + c = 0)
Handles real and complex solutions
Discriminant analysis

💯 Percentage Calculator

Percentage of a number
Percentage increase/decrease
"What percentage is X of Y?"

📏 Trigonometry

Sin, cos, tan (and inverse functions)
Angle calculations in degrees
Precise floating-point results

🚀 Installation

Prerequisites

Node.js >= 18.0.0
npm or yarn

Clone and Install

git clone https://github.com/Ankluna72/Math-Calculator-MCP-Server-.git
cd Math-Calculator-MCP-Server-
npm install
npm run build

⚙️ Configuration

For Claude Desktop

Add to your Claude Desktop config file (claude_desktop_config.json):

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "math-calculator": {
      "command": "node",
      "args": [
        "C:\\path\\to\\Math-Calculator-MCP-Server-\\dist\\index.js"
      ]
    }
  }
}

For VSCode with Cline Extension

Add to VSCode settings (.vscode/settings.json or User Settings):

{
  "mcp.servers": {
    "math-calculator": {
      "command": "node",
      "args": [
        "C:\\path\\to\\Math-Calculator-MCP-Server-\\dist\\index.js"
      ]
    }
  }
}

📚 Usage Examples

Once configured, your AI assistant can use these tools automatically. Here are some example requests:

Basic Calculations

"Calculate 25 * 4"
"What is the square root of 144?"
"Divide 100 by 7"

Statistics

"Calculate the mean of [10, 20, 30, 40, 50]"
"Find median and mode for these numbers: [5, 3, 5, 2, 8, 5]"
"Give me all statistics for [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"

Unit Conversions

"Convert 100 kilometers to miles"
"How many pounds is 75 kilograms?"
"Convert 32 Fahrenheit to Celsius"

Solve Equations

"Solve x² - 5x + 6 = 0"
"Find solutions for 2x² + 3x - 2 = 0"

Percentages

"What is 15% of 200?"
"Increase 50 by 20%"
"What percentage is 25 of 200?"

Trigonometry

"Calculate sin(30°)"
"What is cos(45°)?"
"Find tan(60°)"

🛠️ Available Tools

Tool	Description
`calculate`	Basic arithmetic operations
`statistics`	Statistical analysis of number arrays
`convert_units`	Convert between different units
`solve_equation`	Solve quadratic equations
`percentage`	Percentage calculations
`trigonometry`	Trigonometric functions

📁 Project Structure

Math-Calculator-MCP-Server-/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (after build)
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
├── .gitignore
└── README.md

🔧 Development

# Install dependencies
npm install

# Build the project
npm run build

# Development mode (watch for changes)
npm run dev

# Start the server
npm start

🧪 Testing

You can test the server manually using stdio communication:

npm start

Then send MCP protocol messages via stdin to test tool execution.

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📧 Contact

Jefferson Rosas Chambilla

GitHub: @Ankluna72
Repository: Math-Calculator-MCP-Server-

🌟 Acknowledgments

Built with the Model Context Protocol SDK
Inspired by the need for mathematical tools in AI assistants
Thanks to Anthropic for developing the MCP standard

TestRail Manager: Automatiza tu Gestión de Pruebas con Python

JEFFERSON ROSAS CHAMBILLA — Fri, 21 Nov 2025 00:58:05 +0000

🚀 TestRail Manager: Automatiza tu Gestión de Pruebas con Python

¿Cansado de gestionar manualmente tus casos de prueba en TestRail? ¿Quieres automatizar el reporte de resultados desde tus tests? TestRail Manager es la solución que necesitas.

🎯 ¿Qué es TestRail Manager?

TestRail Manager es una librería Python completa que te permite interactuar con la API de TestRail de forma simple y eficiente. Con ella puedes:

✅ Crear y gestionar proyectos, suites y casos de prueba

✅ Ejecutar test runs automáticamente

✅ Reportar resultados desde tus frameworks de testing (pytest, unittest, etc.)

✅ Generar métricas y reportes detallados

✅ Integrar TestRail en tu pipeline CI/CD

💡 ¿Por qué la creé?

Como QA Engineer, me encontraba constantemente:

📝 Creando casos de prueba manualmente en TestRail
🔄 Actualizando resultados uno por uno después de cada ejecución
📊 Generando reportes manualmente para los stakeholders
🤯 Perdiendo tiempo en tareas repetitivas

Necesitaba una forma de automatizar todo este proceso y mantener TestRail sincronizado con mis test automatizados. Así nació TestRail Manager.

🛠️ Instalación Rápida

# Clonar el repositorio
git clone https://github.com/Ankluna72/Gestion-de-pruebas-TestRail-Rosas.git
cd Gestion-de-pruebas-TestRail-Rosas

# Instalar dependencias
pip install -r requirements.txt

# Configurar credenciales
copy .env.example .env
# Edita .env con tus credenciales de TestRail

🚦 Inicio Rápido

1️⃣ Configuración Básica

from testrail_manager import TestRailManager
from config import TestRailConfig

# Inicializar el manager
manager = TestRailManager(
    base_url="https://tu-empresa.testrail.io",
    username="tu-email@ejemplo.com",
    api_key="tu-api-key"
)

2️⃣ Crear un Caso de Prueba

# Crear un caso de prueba con pasos detallados
case = manager.create_case(
    section_id=1,
    title="Login exitoso con credenciales válidas",
    type_id=TestRailConfig.TYPE_FUNCTIONAL,
    priority_id=TestRailConfig.PRIORITY_HIGH,
    custom_steps=[
        {
            'content': '1. Abrir página de login',
            'expected': 'Se muestra formulario de login'
        },
        {
            'content': '2. Ingresar credenciales válidas',
            'expected': 'Las credenciales son aceptadas'
        },
        {
            'content': '3. Hacer clic en "Iniciar sesión"',
            'expected': 'Usuario es redirigido al dashboard'
        }
    ],
    estimate='2m'
)

print(f"✓ Caso creado con ID: {case['id']}")

3️⃣ Ejecutar un Test Run

from datetime import datetime

# Crear test run
run = manager.create_run(
    project_id=1,
    suite_id=1,
    name=f"Test Run - {datetime.now().strftime('%Y-%m-%d %H:%M')}",
    description="Ejecución automatizada",
    include_all=True
)

print(f"✓ Test Run creado: {run['id']}")

4️⃣ Reportar Resultados

# Reportar resultado exitoso
result = manager.add_result_for_case(
    run_id=run['id'],
    case_id=case['id'],
    status_id=TestRailConfig.STATUS_PASSED,
    comment="✓ Prueba ejecutada exitosamente",
    elapsed="2m 30s",
    version="v1.2.3"
)

print("✓ Resultado reportado")

5️⃣ Generar Métricas

# Obtener estadísticas del run
stats = manager.get_run_statistics(run_id=run['id'])

print(f"Total de pruebas: {stats['total_tests']}")
print(f"✓ Pasadas: {stats['passed']}")
print(f"✗ Fallidas: {stats['failed']}")
print(f"Tasa de éxito: {stats['pass_rate']:.2f}%")

🔥 Caso de Uso Real: Integración con pytest

Una de las funcionalidades más potentes es la integración con pytest para reportar automáticamente los resultados a TestRail.

import pytest
from testrail_manager import TestRailManager
from config import TestRailConfig

# Configurar TestRail
testrail = TestRailManager(
    base_url=TestRailConfig.BASE_URL,
    username=TestRailConfig.USERNAME,
    api_key=TestRailConfig.API_KEY
)

class TestLogin:
    def test_login_exitoso(self):
        # Tu lógica de test
        resultado = perform_login("user@test.com", "password123")

        # Reportar a TestRail automáticamente
        testrail.add_result_for_case(
            run_id=123,
            case_id=456,
            status_id=1 if resultado else 5,
            comment="Test ejecutado desde pytest",
            elapsed="500ms"
        )

        assert resultado == True

📊 Ejemplo Completo: Pipeline de Testing

Aquí un ejemplo de cómo usar TestRail Manager en un pipeline completo:

from testrail_manager import TestRailManager
from config import TestRailConfig
import time

# 1. Inicializar
manager = TestRailManager(
    base_url=TestRailConfig.BASE_URL,
    username=TestRailConfig.USERNAME,
    api_key=TestRailConfig.API_KEY
)

# 2. Crear test run
run = manager.create_run(
    project_id=1,
    suite_id=1,
    name="Regression Suite - Nightly",
    description="Ejecución nocturna automática"
)

# 3. Obtener tests
tests = manager.get_tests(run['id'])

# 4. Ejecutar y reportar
for test in tests:
    start_time = time.time()

    try:
        # Ejecutar tu test aquí
        result = execute_test(test['case_id'])

        # Reportar éxito
        manager.add_result(
            test_id=test['id'],
            status_id=TestRailConfig.STATUS_PASSED,
            comment=f"✓ Test pasó correctamente",
            elapsed=f"{int(time.time() - start_time)}s"
        )
    except Exception as e:
        # Reportar fallo
        manager.add_result(
            test_id=test['id'],
            status_id=TestRailConfig.STATUS_FAILED,
            comment=f"✗ Error: {str(e)}",
            elapsed=f"{int(time.time() - start_time)}s"
        )

# 5. Generar reporte
stats = manager.get_run_statistics(run['id'])
manager.generate_run_report(run['id'], 'report.txt')

# 6. Cerrar run
manager.close_run(run['id'])

print(f"✅ Pipeline completado - Tasa de éxito: {stats['pass_rate']:.2f}%")

🎁 Características Destacadas

🔧 API Completa

La librería cubre prácticamente toda la API de TestRail:

Proyectos: Crear, listar, obtener detalles
Suites: Organizar casos en suites de prueba
Secciones: Estructurar casos en secciones
Casos: CRUD completo con campos personalizados
Test Runs: Gestión completa de ejecuciones
Resultados: Reporte individual o en lote
Métricas: Estadísticas y reportes automáticos

🛡️ Manejo Robusto de Errores

try:
    case = manager.create_case(
        section_id=999999,  # ID inexistente
        title="Test Case"
    )
except Exception as e:
    print(f"Error: {e}")
    # Salida: Error en la petición a TestRail: 404 Not Found

📦 Ejemplos Incluidos

El repositorio incluye 4 ejemplos prácticos listos para usar:

example_basic.py - Operaciones fundamentales
example_create_test_run.py - Crear y ejecutar test runs
example_manage_cases.py - Gestión de casos de prueba
example_integration_pytest.py - Integración con pytest

🏗️ Arquitectura del Proyecto

testrail-manager/
│
├── testrail_manager.py    # Clase principal
├── config.py              # Configuración
├── requirements.txt       # Dependencias
├── .env.example          # Plantilla de credenciales
│
├── examples/             # Ejemplos prácticos
│   ├── example_basic.py
│   ├── example_create_test_run.py
│   ├── example_manage_cases.py
│   └── example_integration_pytest.py
│
└── README.md             # Documentación completa

🔐 Seguridad

La herramienta sigue las mejores prácticas de seguridad:

✅ Credenciales en variables de entorno (nunca en el código)

✅ .gitignore configurado para evitar exposición

✅ Manejo seguro de API Keys

✅ Validación de configuración antes de ejecutar

# Configuración segura con .env
TESTRAIL_URL=https://tu-empresa.testrail.io
TESTRAIL_USERNAME=tu-email@ejemplo.com
TESTRAIL_API_KEY=tu-api-key

📈 Métricas y Reportes

Genera reportes detallados automáticamente:

# Obtener estadísticas
stats = manager.get_run_statistics(run_id=123)

# Generar reporte
report = manager.generate_run_report(
    run_id=123,
    output_file='test_report.txt'
)

Salida del reporte:

============================================================
REPORTE DE TEST RUN - Regression Suite
============================================================

Run ID: 123
Fecha: 2025-11-20 10:30:00

RESUMEN DE PRUEBAS:
============================================================
Total de pruebas:    50
Pasadas:             45 (90.00%)
Fallidas:            3
Bloqueadas:          1
Para re-probar:      0
Sin probar:          1

🚀 Casos de Uso

1. CI/CD Integration

# GitHub Actions ejemplo
name: Run Tests and Report to TestRail

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run tests
        run: pytest
      - name: Report to TestRail
        run: python report_to_testrail.py
        env:
          TESTRAIL_URL: ${{ secrets.TESTRAIL_URL }}
          TESTRAIL_USERNAME: ${{ secrets.TESTRAIL_USERNAME }}
          TESTRAIL_API_KEY: ${{ secrets.TESTRAIL_API_KEY }}

2. Selenium Integration

from selenium import webdriver
from testrail_manager import TestRailManager

driver = webdriver.Chrome()
manager = TestRailManager(...)

try:
    driver.get("https://app.com/login")
    # ... tu test ...

    manager.add_result_for_case(
        run_id=123,
        case_id=456,
        status_id=1,
        comment="✓ Selenium test passed"
    )
finally:
    driver.quit()

3. Scheduled Reports

# Script para generar reportes diarios
from datetime import datetime
from testrail_manager import TestRailManager

manager = TestRailManager(...)

# Obtener runs activos
runs = manager.get_runs(project_id=1)

for run in runs:
    if run.get('is_completed') == False:
        stats = manager.get_run_statistics(run['id'])

        # Enviar por email, Slack, etc.
        send_notification(
            f"Run: {run['name']}\n"
            f"Progress: {stats['pass_rate']:.2f}%"
        )

📚 Recursos Adicionales

🔗 Enlaces Útiles

📦 Repositorio: GitHub - TestRail Manager
📖 Documentación Completa: Ver README.md en el repo
🐛 Reportar Issues: GitHub Issues
📘 TestRail API Docs: Documentación oficial

💻 Requisitos

Python 3.7+
TestRail (cuenta con acceso a API)
requests >= 2.25.0
python-dotenv >= 0.19.0

🎯 Próximos Pasos

Estoy trabajando en nuevas características:

[ ] Soporte para attachments en resultados
[ ] CLI tool para operaciones comunes
[ ] Dashboard web para visualizar métricas
[ ] Exportación a PDF/Excel
[ ] Webhooks para notificaciones en tiempo real

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Si tienes ideas o encuentras bugs:

🍴 Fork el repositorio
🔨 Crea tu feature branch
✅ Haz commit de tus cambios
🚀 Push a la rama
📬 Abre un Pull Request

💬 Feedback

¿Qué te parece la herramienta? ¿La usarías en tus proyectos? Déjame tus comentarios abajo 👇

Si te resultó útil:

⭐ Dale una estrella en GitHub
🔄 Compártelo con tu equipo
💬 Déjame saber cómo la estás usando

📞 Contacto

GitHub: @Ankluna72
Proyecto: TestRail Manager

🎬 Conclusión

TestRail Manager es una herramienta completa que te permite:

✅ Ahorrar tiempo automatizando tareas repetitivas

✅ Mejorar la calidad con mejor trazabilidad

✅ Integrar TestRail en tu pipeline de CI/CD

✅ Generar reportes automáticos y detallados

¿Listo para automatizar tu gestión de pruebas? 🚀

👉 Prueba TestRail Manager ahora

Tags: #testing #python #automation #testrail #qa #devops #cicd #pytest #selenium

Desarrollado con ❤️ para la comunidad de QA

[Boost]

JEFFERSON ROSAS CHAMBILLA — Fri, 17 Oct 2025 02:08:35 +0000

Applying Postman for API Testing: Real-World Examples

JEFFERSON ROSAS CHAMBILLA ・ Oct 17

#webdev

Applying Postman for API Testing: Real-World Examples

JEFFERSON ROSAS CHAMBILLA — Fri, 17 Oct 2025 01:57:20 +0000

Applying Postman for API Testing: Real-World Examples

API testing is a critical part of modern software development, ensuring that APIs are reliable, performant, and secure. Among the top tools for API testing in 2022, Postman stands out for its user-friendly interface and robust features, making it ideal for both beginners and experienced testers. In this article, we’ll explore how to apply Postman as an API testing framework, with real-world code examples to demonstrate its power. This is inspired by insights from Alice Aldaine’s article on API testing tools.

Why Postman?

Postman is a versatile tool that supports REST API testing without requiring extensive coding knowledge. Its key features include:

Ease of Use: A rich interface for creating and managing API requests.
Automation: Supports automated testing with JavaScript-based scripts.
Integrations: Works with Swagger, RAML, and CI/CD pipelines.
Collaboration: Allows teams to share collections of requests and responses.

Whether you’re testing a public API or building your own, Postman simplifies the process. Let’s dive into real-world examples to see it in action.

Setting Up Postman

To get started, download Postman from getpostman.com and install it on your system (Mac, Windows, or Linux). The free tier is sufficient for most testing needs, though paid plans ($12/user/month) offer advanced collaboration features.

Once installed, create a new Collection to organize your API requests. For this article, we’ll test the JSONPlaceholder API, a free fake API for testing.

Real-World Example 1: Testing a GET Request

Let’s test a GET request to retrieve a list of users from JSONPlaceholder.

Create a Request:
- In Postman, click New > Request.
- Name it “Get Users” and save it to your collection.
- Set the request URL to https://jsonplaceholder.typicode.com/users.
Send the Request:
- Click Send to execute the GET request.
- You should see a JSON response with a list of user objects.
Add Tests:
Postman allows you to write JavaScript test scripts to validate responses. In the Tests tab of the request, add the following script:

   pm.test("Status code is 200", function () {
       pm.response.to.have.status(200);
   });

   pm.test("Response contains users", function () {
       var jsonData = pm.response.json();
       pm.expect(jsonData).to.be.an('array').that.is.not.empty;
       pm.expect(jsonData[0]).to.have.property('name');
   });

This script checks:

The response status is 200 (OK).
The response is a non-empty array.
The first user object has a name property.

Run the Test:
- Send the request again. The Test Results tab will show the test outcomes (e.g., “2/2 tests passed”).

This example is typical in real-world scenarios where you verify that an API returns expected data structures, such as user lists in a social media app.

Real-World Example 2: Testing a POST Request

Now, let’s test creating a new post, simulating a scenario where a user submits content to a blog platform.

Create a POST Request:
- Create a new request named “Create Post”.
- Set the method to POST and the URL to https://jsonplaceholder.typicode.com/posts.
- In the Body tab, select raw and JSON, then add:

   {
       "title": "My New Post",
       "body": "This is a test post created via Postman.",
       "userId": 1
   }

Add Tests: In the Tests tab, add:

   pm.test("Status code is 201", function () {
       pm.response.to.have.status(201);
   });

   pm.test("Response contains post details", function () {
       var jsonData = pm.response.json();
       pm.expect(jsonData).to.have.property('id');
       pm.expect(jsonData.title).to.equal("My New Post");
       pm.expect(jsonData.body).to.equal("This is a test post created via Postman.");
       pm.expect(jsonData.userId).to.equal(1);
   });

This validates that the API creates a new post with the correct data and returns a 201 (Created) status.

Run and Verify:
- Send the request and check the Test Results. The API will return the posted data with a new id.

This mirrors real-world use cases like submitting user-generated content to a CMS or e-commerce platform.

Real-World Example 3: Automating Tests with Collections

In a CI/CD pipeline, you might want to automate multiple API tests. Postman’s Collection Runner makes this easy.

Create a Collection:
- Add the “Get Users” and “Create Post” requests to a collection named “JSONPlaceholder Tests”.
Run the Collection:
- Open the Collection Runner, select your collection, and click Run.
- Postman executes all requests sequentially and displays test results.
Export for CI/CD:
- Export the collection as a JSON file.
- Use Newman (Postman’s CLI tool) to run it in a CI pipeline. Install Newman via npm:

   npm install -g newman

Run the collection:

   newman run JSONPlaceholder_Tests.json

This is invaluable for teams integrating API tests into Jenkins or GitHub Actions, ensuring APIs are tested with every code change.

Embedding Rich Content

To visualize the power of Postman, check out this quick demo:

This YouTube video shows Postman’s interface and basic request setup, complementing our examples.

Conclusion

Postman is a powerful, accessible framework for API testing, suitable for both manual and automated workflows. Its scripting capabilities, collection management, and CI/CD integration make it a go-to choice for real-world API testing. As noted in Alice Aldaine’s article, Postman’s ease of use and lack of required coding knowledge make it ideal for diverse teams.

Try Postman with your own APIs, and explore its advanced features like mock servers and monitoring to take your testing to the next level. Happy testing!

References

Applying Bandit SAST Tool to Secure Python Applications

JEFFERSON ROSAS CHAMBILLA — Wed, 24 Sep 2025 00:26:03 +0000

Why Bandit for Python Security?

Bandit is an open-source SAST tool developed by the OpenStack Security Project that specializes in analyzing Python code for common security issues. It's particularly valuable because:

Python-specific analysis - Understands Python idioms and common patterns
Plugin-based architecture - Extensible with custom checks
CI/CD friendly - Designed for automation
Zero cost - Completely free and open-source

Common Vulnerabilities Bandit Detects

SQL injection vulnerabilities
Shell injection risks
Hardcoded passwords and secrets
Use of insecure modules
Input validation issues
Information disclosure risks

Hands-On: Implementing Bandit

Installation

# Install using pip
pip install bandit

# Or install from source
git clone https://github.com/PyCQA/bandit.git
cd bandit
pip install .

Basic Usage

# Scan a single file
bandit my_script.py

# Scan an entire directory
bandit -r my_project/

# Generate HTML report
bandit -r my_project/ -f html -o report.html

# Scan with specific security level
bandit -r my_project/ -l high

Sample Vulnerable Python Code

# vulnerable_app.py
import os
import pickle
import subprocess
import sqlite3

def process_user_input():
    # Vulnerability: Code injection
    user_input = input("Enter command: ")
    os.system(user_input)  # B602: subprocess_popen_with_shell_equals_true

def database_operations():
    # Vulnerability: SQL injection
    username = input("Enter username: ")
    conn = sqlite3.connect('users.db')
    cursor = conn.cursor()
    cursor.execute(f"SELECT * FROM users WHERE username = '{username}'")  # B608: hardcoded_sql_expressions

def data_deserialization():
    # Vulnerability: Insecure deserialization
    data = input("Enter serialized data: ")
    obj = pickle.loads(data.encode())  # B301: blacklist

Running Bandit Scan

bandit -r vulnerable_app.py -f txt

Sample Bandit Output

Results generated:
>> Issue: [B602:subprocess_popen_with_shell_equals_true] Using subprocess with shell=True
   Severity: High   Confidence: High
   Location: vulnerable_app.py:8
   More Info: https://bandit.readthedocs.io/en/latest/blacklists/blacklist_calls.html#b602-subprocess-popen-with-shell-equals-true
7    user_input = input("Enter command: ")
8    os.system(user_input)

>> Issue: [B608:hardcoded_sql_expressions] Possible SQL injection vector through string-based query construction.
   Severity: Medium   Confidence: Medium
   Location: vulnerable_app.py:15
15    cursor.execute(f"SELECT * FROM users WHERE username = '{username}'")

>> Issue: [B301:blacklist] Use of unsafe deserialization function.
   Severity: High   Confidence: High
   Location: vulnerable_app.py:20
20    obj = pickle.loads(data.encode())

Advanced Bandit Configuration

Custom Configuration File

# bandit.yml
exclude_dirs: ['tests', 'venv', 'migrations']
skips: ['B101', 'B102']
tests: ['B301', 'B302', 'B601', 'B602']

targets:
  - src/
  - app/

output_format: json
verbose: true

Using Configuration File

bandit -c bandit.yml -r my_project/

CI/CD Integration (GitHub Actions)

name: Security Scan with Bandit
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install Bandit
        run: pip install bandit

      - name: Run Bandit Security Scan
        run: bandit -r . -f json -o bandit-report.json

      - name: Upload Bandit Report
        uses: actions/upload-artifact@v3
        with:
          name: bandit-report
          path: bandit-report.json

Bandit Test Types and Severity Levels

Severity Levels

Low: Code quality issues, minor security concerns
Medium: Potential security vulnerabilities
High: Critical security vulnerabilities

Common Test IDs

B1xx: Various general tests
B2xx: Application/framework-specific issues
B3xx: Blacklisted imports and functions
B4xx: Using insecure random generators
B5xx: SSL/TLS issues
B6xx: Shell injection vulnerabilities
B7xx: Pickle and YAML deserialization

Custom Bandit Plugins

Creating Custom Tests

# custom_checks.py
import bandit
from bandit.core import test_properties as test

@test.checks('Call')
@test.test_id('B901')
def hardcoded_api_key(context):
    """Check for hardcoded API keys"""
    suspicious_strings = ['api_key', 'secret_key', 'password']
    if context.call_function_name_qual in suspicious_strings:
        return bandit.Issue(
            severity=bandit.HIGH,
            confidence=bandit.MEDIUM,
            text="Potential hardcoded API key detected"
        )

Using Custom Plugins

bandit -r my_project/ -p custom_checks.py

Best Practices for Bandit Implementation

1. Integrate Early in Development

# Pre-commit hook example
# .git/hooks/pre-commit
#!/bin/bash
bandit -r . -l high -i

2. Regular Scheduled Scans

# GitHub Actions scheduled scan
on:
  schedule:
    - cron: '0 2 * * 1'  # Weekly scan

3. Baseline Establishment

# Establish baseline ignoring existing issues
bandit -r . --baseline baseline.json

4. Quality Gates

# Fail build on high severity issues
bandit -r . -l high --exit-zero

Limitations and Considerations

While Bandit is powerful, it's important to understand its limitations:

Static analysis only - Cannot detect runtime issues
Python-specific - Only works with Python code
Pattern-based - May produce false positives/negatives
No data flow analysis - Limited context awareness

Conclusion

Bandit provides an excellent open-source SAST solution for Python applications. Its ease of use, comprehensive vulnerability detection, and seamless CI/CD integration make it an essential tool for any Python developer concerned with security.

By implementing Bandit in your development workflow, you can catch common security issues early, reduce remediation costs, and build more secure Python applications.

🔍 Applying Flawfinder: A Lightweight SAST Tool to Secure C/C++ Codebases

JEFFERSON ROSAS CHAMBILLA — Tue, 23 Sep 2025 21:59:34 +0000

Introduction: Why SAST for C/C++?

Static Application Security Testing (SAST) is a foundational practice in modern secure software development. Unlike dynamic or runtime analysis, SAST examines source code without executing it, identifying vulnerabilities early in the development lifecycle when they are cheapest and easiest to fix.

While enterprise-grade tools often dominate the conversation, lightweight, open-source alternatives like Flawfinder offer tremendous value. This is especially true for teams working with C/C++, embedded systems, or legacy codebases where simplicity, speed, and zero cost are critical.

In this article, we'll apply Flawfinder to a sample C++ program, interpret its findings, and discuss how to integrate it into a development workflow.

Why Flawfinder?

Flawfinder is a command-line static analysis tool designed specifically for C and C++. Created by David A. Wheeler, it scans source code for calls to functions known to be risky (like strcpy, gets, sprintf) which commonly lead to:

Buffer overflows (CWE-120)
Format string vulnerabilities (CWE-134)
Command injection (CWE-78)

Instead of performing complex abstract syntax tree (AST) analysis, Flawfinder uses simple but effective pattern-matching against a curated database of dangerous function calls. This makes it:

✅ Blazingly fast - Scans thousands of lines of code in seconds.
✅ Lightweight - No compilation or complex setup required.
✅ Free and Open-Source - No licensing fees.
✅ Beginner-friendly - Easy to install and interpret results.

And as requested, it's not SonarQube, Snyk, Semgrep, or Veracode.

Hands-On: Scanning a C++ Project

Step 1: Installation

Installing Flawfinder is straightforward. It's available via package managers for most Linux distributions and macOS.

# On Ubuntu/Debian
sudo apt-get install flawfinder

# On macOS using Homebrew
brew install flawfinder

# Using pip (Python Package Manager)
pip install flawfinder

Verify the installation:

flawfinder --version

Step 2: Create a Sample C++ File to Scan

Let's create a simple C++ file (vulnerable_example.cpp) that contains some common security pitfalls. This will give Flawfinder something interesting to report.

// vulnerable_example.cpp
#include <iostream>
#include <cstring>
#include <cstdio>

int main() {
    char src[10] = "Hello";
    char dest[5]; // Oops! Too small.

    // 1. Risky function: strcpy (potential buffer overflow)
    strcpy(dest, src);

    // 2. Risky function: sprintf (potential buffer overflow)
    char buffer[10];
    sprintf(buffer, "The number is %d", 42);

    // 3. Risky function: gets (extremely dangerous)
    // char input[50];
    // gets(input); // Uncommenting this would be a major flaw!

    std::cout << "Dest: " << dest << std::endl;
    std::cout << "Buffer: " << buffer << std::endl;

    return 0;
}

Step 3: Run the Scan

Navigate to the directory containing your source file and run Flawfinder. You can point it to a single file or an entire directory.

# Scan a single file
flawfinder vulnerable_example.cpp

# Scan the current directory and all subdirectories
flawfinder ./

Step 4: Interpreting the Results

Flawfinder's output is color-coded and ranked by risk level (0-5, where 5 is the most severe). Here's what you might see for our example:

Flawfinder version 2.0.19, (C) 2001-2019 David A. Wheeler.
Number of rules (primarily dangerous function names) in C/C++ ruleset: 220
Examining vulnerable_example.cpp

vulnerable_example.cpp:10: [4] (buffer) strcpy:
  Does not check for buffer overflows when copying to destination (CWE-120).
  Consider using strncpy or snprintf.

vulnerable_example.cpp:14: [4] (buffer) sprintf:
  Does not check for buffer overflows when writing to destination (CWE-120).
  Use snprintf or vsnprintf instead.

vulnerable_example.cpp:18: [5] (buffer) gets:
  This function is extremely dangerous because it may overflow the
  calling buffer. It is obsoleted by ISO/IEC 9899:1999 (C99) and
  should never be used. Use fgets() instead.

FINAL RESULTS:

Hits = 3
Lines analyzed = 20 in 0.1 seconds (200 lines/second)
3 Physical Source Lines of Code (SLOC) = 20
Hits@level = [0]   0 [1]   0 [2]   0 [3]   0 [4]   2 [5]   1
Hits@level+ = [0+]   3 [1+]   3 [2+]   3 [3+]   3 [4+]   3 [5+]   1

Key takeaways from the report:

Location: Each finding shows the file and line number.
Risk Level: [4] and [5] indicate high-severity issues.
Description: A brief explanation of the risk and the associated CWE.
Recommendation: Suggests safer alternative functions.

Integrating Flawfinder into Your Workflow

To move beyond one-off scans, you can integrate Flawfinder directly into your development process.

1. Make it Part of Your CI/CD Pipeline (e.g., GitHub Actions)

You can create a simple GitHub Action to run Flawfinder on every push or pull request. Create a file in your repo at .github/workflows/flawfinder.yml:

name: SAST with Flawfinder
on: [push, pull_request]

jobs:
  sast:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Flawfinder
        run: sudo apt-get install -y flawfinder

      - name: Run Flawfinder
        run: flawfinder --sarflib ./

This will output the results in SARIF format, which GitHub can natively display in the "Security" tab.

2. Customizing Scans with Command-Line Options

Flawfinder offers several options to tailor the output:

# Only show high-risk issues (level 4 and 5)
flawfinder --minlevel 4 ./

# Generate a HTML report
flawfinder --html --output results.html ./

# Suppress specific known issues (e.g., a false positive on line 10)
flawfinder --falsepositive vulnerable_example.cpp:10

Limitations and Considerations

While Flawfinder is excellent for catching known dangerous patterns, it's important to understand its limitations:

False Positives: Pattern-matching can flag safe usage of functions
Limited Scope: Only finds issues related to its built-in database
No Data Flow Analysis: Cannot track variables across complex function calls

For mission-critical projects, consider using Flawfinder alongside more advanced tools like Clang Static Analyzer or commercial solutions.

Conclusion: Flawfinder's Place in Your Toolbox

Flawfinder is not a silver bullet. Its pattern-matching approach can produce false positives and it won't catch complex logical flaws. However, as a fast, free, and focused tool, it is incredibly effective at what it does: catching obvious yet dangerous function calls in C/C++ code.

It serves as an excellent first line of defense, especially for developers new to secure coding practices. By integrating it early and often, you can prevent well-known vulnerability classes from ever reaching production.