Skip to content

docs: update testing strategy and plugin development workflows#53

Open
msureshkumar88 wants to merge 7 commits intomainfrom
docs/update-testing-strategy-and-workflows
Open

docs: update testing strategy and plugin development workflows#53
msureshkumar88 wants to merge 7 commits intomainfrom
docs/update-testing-strategy-and-workflows

Conversation

@msureshkumar88
Copy link
Copy Markdown
Collaborator

@msureshkumar88 msureshkumar88 commented Apr 24, 2026 •
edited
Loading

Summary

Updates cpex-plugins documentation to reflect the latest agreement on testing strategy and plugin development workflows.

Changes

Testing Strategy

Test Locations:

  • Unit tests: Present in cpex-plugins/tests/ - Test plugin logic in isolation
  • Integration tests: Present in mcp-context-forge/tests/integration/ - Test plugin integration with gateway
  • E2E tests: Present in mcp-context-forge/tests/e2e/ - Test complete workflows with plugins

This separation ensures:

  • Fast feedback during plugin development (unit tests in cpex-plugins)
  • System-level validation (integration/E2E tests in mcp-context-forge)
  • Clear separation of concerns between repositories

Plugin Development Workflow

Where to Develop:

  • All plugins are developed in the cpex-plugins repository
  • Plugin code location: plugins/rust/python-package/<slug>/
  • Unit tests written in cpex-plugins/tests/

Current Workflow (Rust + Python Hybrid):

  1. Create plugin using make plugin-scaffold in cpex-plugins
  2. Implement Rust core logic + Python entry points (PyO3/maturin)
  3. Write unit tests in cpex-plugins/tests/
  4. Build and test locally: make install && make test-all
  5. Create PR in cpex-plugins with unit tests
  6. After merge, coordinate with mcp-context-forge team
  7. Write integration/E2E tests in mcp-context-forge/tests/
  8. Release via tag: <slug>-v<version> (triggers PyPI publish)

Future Workflow (Pure Rust - Post Framework Migration):

  1. Create plugin using cargo new --lib in cpex-plugins
  2. Implement pure Rust plugin (no Python entry points)
  3. Write unit tests in cpex-plugins/tests/
  4. Build and test locally: cargo build && cargo test
  5. Create PR in cpex-plugins with unit tests
  6. After merge, coordinate with mcp-context-forge team
  7. Write integration/E2E tests in mcp-context-forge/tests/
  8. Release via Cargo registry

Key Points:

  • Plugins are ONLY developed using Rust (core implementation)
  • Python entry points are temporary (current hybrid approach)
  • After plugin framework migrates to Rust, Python components will be removed
  • Unit tests always stay in cpex-plugins
  • Integration/E2E tests always stay in mcp-context-forge

Cross-Repository Coordination

Development Flow:

  1. Develop plugin in cpex-plugins → Write unit tests → Create PR
  2. After cpex-plugins PR merged → Coordinate with mcp-context-forge
  3. Write integration/E2E tests in mcp-context-forge → Create PR
  4. Both repositories CI must pass before release

Files Updated

  1. AGENTS.md

    • Added comprehensive testing strategy section
    • Documented where unit tests reside (cpex-plugins)
    • Documented where integration/E2E tests reside (mcp-context-forge)
    • Added detailed plugin development workflows (current and future)
    • Added cross-repository coordination guidelines

  2. DEVELOPING.md

    • Expanded repository model with current and future architecture
    • Added complete 7-step plugin development workflow for both scenarios
    • Added integration testing coordination with mcp-context-forge
    • Added migration path documentation
    • Clarified test locations for each workflow step

  3. TESTING.md

    • Complete rewrite with testing architecture section
    • Clearly documented test locations by type
    • Added cross-repository testing workflow
    • Added testing coordination guidelines
    • Added future pure Rust testing approach
    • Added debugging and best practices sections

  4. README.md

    • Added testing strategy summary with test locations
    • Added current/future architecture overview
    • Added plugin development workflow summary
    • Updated with proper cross-references to detailed docs

Documentation Consistency

All documentation uses consistent:

  • ✅ Terminology and naming conventions
  • ✅ File paths and directory structures
  • ✅ Command examples and workflows
  • ✅ Cross-references between documents
  • ✅ Testing locations and scopes
  • ✅ Clear separation: unit tests in cpex-plugins, integration/E2E in mcp-context-forge
  • ✅ Plugin development workflow: start in cpex-plugins, coordinate with mcp-context-forge

Related Issue

Closes #20

Suresh Kumar Moharajan added 7 commits April 24, 2026 11:54
feat: add plugin scaffold generator
a622917 
Implements an interactive plugin scaffold generator that creates complete
plugin structures from Jinja2 templates.

Features:
- Interactive CLI with prompts for plugin metadata
- Non-interactive mode for automation
- Generates all required files (Cargo.toml, pyproject.toml, Makefile, etc.)
- Creates Python package with type stubs
- Creates Rust source with PyO3 bindings
- Includes test scaffolding and optional benchmarks
- Automatically updates workspace Cargo.toml
- Validates plugin name and configuration

Usage:
  make plugin-scaffold              # Interactive mode
  python3 tools/scaffold_plugin.py --help  # See all options

Components:
- tools/scaffold_plugin.py: Main generator script
- tools/templates/plugin/: Jinja2 templates for all plugin files
- Makefile: Added plugin-scaffold and plugin-scaffold-help targets

The generator follows patterns from existing plugins (url_reputation,
pii_filter, etc.) and ensures consistency across the codebase.

Tested with make plugins-validate - all checks pass.

Signed-off-by: Suresh Kumar Moharajan <suresh.kumar.m@ibm.com>
feat: add all 12 hooks from mcp-context-forge to scaffold tool
314efb4 
- Add agent hooks (agent_pre_invoke, agent_post_invoke)
- Add HTTP hooks (http_pre_request, http_post_request, http_auth_resolve_user, http_auth_check_permission)
- Organize hooks by category with comments
- Total of 12 hooks across 5 categories now available for plugin scaffolding

Signed-off-by: Suresh <suresh@example.com>
Signed-off-by: Suresh Kumar Moharajan <suresh.kumar.m@ibm.com>
feat: enhance test template with comprehensive unit tests
a60909e 
- Remove TODO placeholders for integration and performance tests
- Add unit tests for config deserialization and immutability
- Add unit tests for None value handling
- Add edge case tests for empty strings and special characters
- Add config roundtrip serialization test
- Focus on unit-level testing within plugin directory scope

Signed-off-by: Suresh <suresh@example.com>
Signed-off-by: Suresh Kumar Moharajan <suresh.kumar.m@ibm.com>
feat: add basic Rust unit tests to engine template
f46f280 
- Add test_engine_creation_with_defaults test
- Add test_engine_creation_with_custom_config test
- Remove TODO placeholder and provide concrete test implementations
- Tests verify engine initialization and configuration handling

Signed-off-by: Suresh <suresh@example.com>
Signed-off-by: Suresh Kumar Moharajan <suresh.kumar.m@ibm.com>
docs: add plugin scaffold generator documentation to README
b34ec0e 
- Add 'Creating a New Plugin' section with scaffold usage
- Document all 12 available hooks across 5 categories
- Include interactive and non-interactive mode examples
- Update helper commands section with plugin-scaffold target
- Provide clear guidance for new plugin development

Signed-off-by: Suresh <suresh@example.com>
Signed-off-by: Suresh Kumar Moharajan <suresh.kumar.m@ibm.com>
docs: add plugin scaffold generator to DEVELOPING guide
0bae9c5 
- Add 'Using the Plugin Scaffold Generator' section
- Document recommended workflow for creating new plugins
- Include interactive and non-interactive mode examples
- Clarify manual creation as alternative approach
- Update plugin creation workflow with scaffold-first approach

Signed-off-by: Suresh <suresh@example.com>
Signed-off-by: Suresh Kumar Moharajan <suresh.kumar.m@ibm.com>
docs: update testing strategy and plugin development workflows
5b79869 
- Add comprehensive testing strategy section to AGENTS.md
  - Document unit tests in cpex-plugins
  - Document integration/E2E tests in mcp-context-forge
  - Add cross-repository coordination guidelines

- Expand DEVELOPING.md with detailed workflows
  - Current workflow: Rust + Python hybrid
  - Future workflow: Pure Rust (post-framework migration)
  - Add integration testing coordination
  - Document migration path

- Rewrite TESTING.md with testing architecture
  - Add cross-repository testing workflow
  - Add testing coordination guidelines
  - Add future pure Rust testing approach
  - Add debugging and best practices sections

- Update README.md with testing strategy summary
  - Add current/future architecture overview
  - Add proper cross-references to detailed docs

Closes #20

Signed-off-by: Suresh Kumar Moharajan <suresh.kumar.m@ibm.com>
@lucarlig
Copy link
Copy Markdown
Collaborator

lucarlig commented Apr 29, 2026 •
edited
Loading

@msureshkumar88 this needs to be rebased so that I can review and merge

@msureshkumar88
Copy link
Copy Markdown
Collaborator Author

msureshkumar88 commented Apr 30, 2026

Reviewing python side implementation documentation at the movement will update bock docs together

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@lucarlig lucarlig Awaiting requested review from lucarlig lucarlig is a code owner

@gandhipratik203 gandhipratik203 Awaiting requested review from gandhipratik203 gandhipratik203 is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Move plugin-owned testing into cpex-plugins to support removing redundant Python fallbacks

4 participants

@msureshkumar88 @lucarlig @gcgoncalves @brian-hussey