diff --git a/.gitignore b/.gitignore index c644f148..3a0100d7 100644 --- a/.gitignore +++ b/.gitignore @@ -44,13 +44,7 @@ CLAUDE.local.md .claude/settings.local.json # Project-specific -_bmad-core -_bmad-creator-tools -flattened-codebase.xml *.stats.md -.internal-docs/ -#UAT template testing output files -tools/template-test-generator/test-scenarios/ # Bundler temporary files and generated bundles .bundler-temp/ @@ -58,8 +52,6 @@ tools/template-test-generator/test-scenarios/ # Generated web bundles (built by CI, not committed) src/modules/bmm/sub-modules/ src/modules/bmb/sub-modules/ -src/modules/cis/sub-modules/ -src/modules/bmgd/sub-modules/ shared-modules z*/ diff --git a/src/core/module.yaml b/src/core/module.yaml deleted file mode 100644 index b05b1992..00000000 --- a/src/core/module.yaml +++ /dev/null @@ -1,25 +0,0 @@ -code: core -name: "BMadโ„ข Core Module" - -header: "BMadโ„ข Core Configuration" -subheader: "Configure the core settings for your BMadโ„ข installation.\nThese settings will be used across all modules and agents." - -user_name: - prompt: "What shall the agents call you (TIP: Use a team name if using with a group)?" - default: "BMad" - result: "{value}" - -communication_language: - prompt: "Preferred chat language/style? (English, Mandarin, English Pirate, etc...)" - default: "English" - result: "{value}" - -document_output_language: - prompt: "Preferred document output language?" - default: "English" - result: "{value}" - -output_folder: - prompt: "Where should default output files be saved unless specified in other modules?" - default: "_bmad-output" - result: "{project-root}/{value}" diff --git a/src/modules/bmgd/_module-installer/installer.js b/src/modules/bmgd/_module-installer/installer.js deleted file mode 100644 index 5d9eca0f..00000000 --- a/src/modules/bmgd/_module-installer/installer.js +++ /dev/null @@ -1,160 +0,0 @@ -const fs = require('fs-extra'); -const path = require('node:path'); -const chalk = require('chalk'); -const platformCodes = require(path.join(__dirname, '../../../../tools/cli/lib/platform-codes')); - -/** - * Validate that a resolved path is within the project root (prevents path traversal) - * @param {string} resolvedPath - The fully resolved absolute path - * @param {string} projectRoot - The project root directory - * @returns {boolean} - True if path is within project root - */ -function isWithinProjectRoot(resolvedPath, projectRoot) { - const normalizedResolved = path.normalize(resolvedPath); - const normalizedRoot = path.normalize(projectRoot); - return normalizedResolved.startsWith(normalizedRoot + path.sep) || normalizedResolved === normalizedRoot; -} - -/** - * BMGD Module Installer - * Standard module installer function that executes after IDE installations - * - * @param {Object} options - Installation options - * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from module.yaml - * @param {Array} options.installedIDEs - Array of IDE codes that were installed - * @param {Object} options.logger - Logger instance for output - * @returns {Promise} - Success status - */ -async function install(options) { - const { projectRoot, config, installedIDEs, logger } = options; - - try { - logger.log(chalk.blue('๐ŸŽฎ Installing BMGD Module...')); - - // Create planning artifacts directory (for GDDs, game briefs, architecture) - if (config['planning_artifacts'] && typeof config['planning_artifacts'] === 'string') { - // Strip project-root prefix variations - const planningConfig = config['planning_artifacts'].replace(/^\{project-root\}\/?/, ''); - const planningPath = path.join(projectRoot, planningConfig); - if (!isWithinProjectRoot(planningPath, projectRoot)) { - logger.warn(chalk.yellow(`Warning: planning_artifacts path escapes project root, skipping: ${planningConfig}`)); - } else if (!(await fs.pathExists(planningPath))) { - logger.log(chalk.yellow(`Creating game planning artifacts directory: ${planningConfig}`)); - await fs.ensureDir(planningPath); - } - } - - // Create implementation artifacts directory (sprint status, stories, reviews) - // Check both implementation_artifacts and implementation_artifacts for compatibility - const implConfig = config['implementation_artifacts'] || config['implementation_artifacts']; - if (implConfig && typeof implConfig === 'string') { - // Strip project-root prefix variations - const implConfigClean = implConfig.replace(/^\{project-root\}\/?/, ''); - const implPath = path.join(projectRoot, implConfigClean); - if (!isWithinProjectRoot(implPath, projectRoot)) { - logger.warn(chalk.yellow(`Warning: implementation_artifacts path escapes project root, skipping: ${implConfigClean}`)); - } else if (!(await fs.pathExists(implPath))) { - logger.log(chalk.yellow(`Creating implementation artifacts directory: ${implConfigClean}`)); - await fs.ensureDir(implPath); - } - } - - // Create project knowledge directory - if (config['project_knowledge'] && typeof config['project_knowledge'] === 'string') { - // Strip project-root prefix variations - const knowledgeConfig = config['project_knowledge'].replace(/^\{project-root\}\/?/, ''); - const knowledgePath = path.join(projectRoot, knowledgeConfig); - if (!isWithinProjectRoot(knowledgePath, projectRoot)) { - logger.warn(chalk.yellow(`Warning: project_knowledge path escapes project root, skipping: ${knowledgeConfig}`)); - } else if (!(await fs.pathExists(knowledgePath))) { - logger.log(chalk.yellow(`Creating project knowledge directory: ${knowledgeConfig}`)); - await fs.ensureDir(knowledgePath); - } - } - - // Log selected game engine(s) - if (config['primary_platform']) { - const platforms = Array.isArray(config['primary_platform']) ? config['primary_platform'] : [config['primary_platform']]; - - const platformNames = platforms.map((p) => { - switch (p) { - case 'unity': { - return 'Unity'; - } - case 'unreal': { - return 'Unreal Engine'; - } - case 'godot': { - return 'Godot'; - } - default: { - return p; - } - } - }); - - logger.log(chalk.cyan(`Game engine support configured for: ${platformNames.join(', ')}`)); - } - - // Handle IDE-specific configurations if needed - if (installedIDEs && installedIDEs.length > 0) { - logger.log(chalk.cyan(`Configuring BMGD for IDEs: ${installedIDEs.join(', ')}`)); - - for (const ide of installedIDEs) { - await configureForIDE(ide, projectRoot, config, logger); - } - } - - logger.log(chalk.green('โœ“ BMGD Module installation complete')); - logger.log(chalk.dim(' Game development workflows ready')); - logger.log(chalk.dim(' Agents: Game Designer, Game Dev, Game Architect, Game SM, Game QA, Game Solo Dev')); - - return true; - } catch (error) { - logger.error(chalk.red(`Error installing BMGD module: ${error.message}`)); - return false; - } -} - -/** - * Configure BMGD module for specific platform/IDE - * @private - */ -async function configureForIDE(ide, projectRoot, config, logger) { - // Validate platform code - if (!platformCodes.isValidPlatform(ide)) { - logger.warn(chalk.yellow(` Warning: Unknown platform code '${ide}'. Skipping BMGD configuration.`)); - return; - } - - const platformName = platformCodes.getDisplayName(ide); - - // Try to load platform-specific handler - const platformSpecificPath = path.join(__dirname, 'platform-specifics', `${ide}.js`); - - try { - if (await fs.pathExists(platformSpecificPath)) { - const platformHandler = require(platformSpecificPath); - - if (typeof platformHandler.install === 'function') { - const success = await platformHandler.install({ - projectRoot, - config, - logger, - platformInfo: platformCodes.getPlatform(ide), - }); - if (!success) { - logger.warn(chalk.yellow(` Warning: BMGD platform handler for ${platformName} returned failure`)); - } - } - } else { - // No platform-specific handler for this IDE - logger.log(chalk.dim(` No BMGD-specific configuration for ${platformName}`)); - } - } catch (error) { - logger.warn(chalk.yellow(` Warning: Could not load BMGD platform-specific handler for ${platformName}: ${error.message}`)); - } -} - -module.exports = { install }; diff --git a/src/modules/bmgd/_module-installer/platform-specifics/claude-code.js b/src/modules/bmgd/_module-installer/platform-specifics/claude-code.js deleted file mode 100644 index 8ad050aa..00000000 --- a/src/modules/bmgd/_module-installer/platform-specifics/claude-code.js +++ /dev/null @@ -1,23 +0,0 @@ -/** - * BMGD Platform-specific installer for Claude Code - * - * @param {Object} options - Installation options - * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from module.yaml - * @param {Object} options.logger - Logger instance for output - * @param {Object} options.platformInfo - Platform metadata from global config - * @returns {Promise} - Success status - */ -async function install() { - // TODO: Add Claude Code specific BMGD configurations here - // For example: - // - Game-specific slash commands - // - Agent party configurations for game dev team - // - Workflow integrations for Unity/Unreal/Godot - // - Game testing framework integrations - - // Currently a stub - no platform-specific configuration needed yet - return true; -} - -module.exports = { install }; diff --git a/src/modules/bmgd/_module-installer/platform-specifics/windsurf.js b/src/modules/bmgd/_module-installer/platform-specifics/windsurf.js deleted file mode 100644 index 46f03c9c..00000000 --- a/src/modules/bmgd/_module-installer/platform-specifics/windsurf.js +++ /dev/null @@ -1,18 +0,0 @@ -/** - * BMGD Platform-specific installer for Windsurf - * - * @param {Object} options - Installation options - * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from module.yaml - * @param {Object} options.logger - Logger instance for output - * @param {Object} options.platformInfo - Platform metadata from global config - * @returns {Promise} - Success status - */ -async function install() { - // TODO: Add Windsurf specific BMGD configurations here - - // Currently a stub - no platform-specific configuration needed yet - return true; -} - -module.exports = { install }; diff --git a/src/modules/bmgd/agents/game-architect.agent.yaml b/src/modules/bmgd/agents/game-architect.agent.yaml deleted file mode 100644 index 7099b6b2..00000000 --- a/src/modules/bmgd/agents/game-architect.agent.yaml +++ /dev/null @@ -1,44 +0,0 @@ -# Game Architect Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-architect.md" - name: Cloud Dragonborn - title: Game Architect - icon: ๐Ÿ›๏ธ - module: bmgd - hasSidecar: false - - persona: - role: Principal Game Systems Architect + Technical Director - identity: Master architect with 20+ years shipping 30+ titles. Expert in distributed systems, engine design, multiplayer architecture, and technical leadership across all platforms. - communication_style: "Speaks like a wise sage from an RPG - calm, measured, uses architectural metaphors about building foundations and load-bearing walls" - principles: | - - Architecture is about delaying decisions until you have enough data - - Build for tomorrow without over-engineering today - - Hours of planning save weeks of refactoring hell - - Every system must handle the hot path at 60fps - - Avoid "Not Invented Here" syndrome, always check if work has been done before - - critical_actions: - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - "When creating architecture, validate against GDD pillars and target platform constraints" - - "Always document performance budgets and critical path decisions" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or initialize a workflow if not already done (optional)" - - - trigger: GA or fuzzy match on game-architecture - exec: "{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture/workflow.md" - description: "[GA] Produce a Scale Adaptive Game Architecture" - - - trigger: PC or fuzzy match on project-context - exec: "{project-root}/_bmad/bmgd/workflows/3-technical/generate-project-context/workflow.md" - description: "[PC] Create optimized project-context.md for AI agent consistency" - - - trigger: CC or fuzzy match on correct-course - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/correct-course/workflow.yaml" - description: "[CC] Course Correction Analysis (when implementation is off-track)" - ide-only: true diff --git a/src/modules/bmgd/agents/game-designer.agent.yaml b/src/modules/bmgd/agents/game-designer.agent.yaml deleted file mode 100644 index 6b654dec..00000000 --- a/src/modules/bmgd/agents/game-designer.agent.yaml +++ /dev/null @@ -1,49 +0,0 @@ -# Game Designer Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-designer.md" - name: Samus Shepard - title: Game Designer - icon: ๐ŸŽฒ - module: bmgd - hasSidecar: false - - persona: - role: Lead Game Designer + Creative Vision Architect - identity: Veteran designer with 15+ years crafting AAA and indie hits. Expert in mechanics, player psychology, narrative design, and systemic thinking. - communication_style: "Talks like an excited streamer - enthusiastic, asks about player motivations, celebrates breakthroughs with 'Let's GOOO!'" - principles: | - - Design what players want to FEEL, not what they say they want - - Prototype fast - one hour of playtesting beats ten hours of discussion - - Every mechanic must serve the core fantasy - - critical_actions: - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - "When creating GDDs, always validate against game pillars and core loop" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or initialize a workflow if not already done (optional)" - - - trigger: BG or fuzzy match on brainstorm-game - exec: "{project-root}/_bmad/bmgd/workflows/1-preproduction/brainstorm-game/workflow.md" - description: "[BG] Brainstorm Game ideas and concepts" - - - trigger: GB or fuzzy match on game-brief - exec: "{project-root}/_bmad/bmgd/workflows/1-preproduction/game-brief/workflow.md" - description: "[GB] Create a Game Brief document" - - - trigger: GDD or fuzzy match on create-gdd - exec: "{project-root}/_bmad/bmgd/workflows/2-design/gdd/workflow.md" - description: "[GDD] Create a Game Design Document" - - - trigger: ND or fuzzy match on narrative-design - exec: "{project-root}/_bmad/bmgd/workflows/2-design/narrative/workflow.md" - description: "[ND] Design narrative elements and story" - - - trigger: QP or fuzzy match on quick-prototype - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-prototype/workflow.yaml" - description: "[QP] Rapid game prototyping - test mechanics and ideas quickly" - ide-only: true diff --git a/src/modules/bmgd/agents/game-dev.agent.yaml b/src/modules/bmgd/agents/game-dev.agent.yaml deleted file mode 100644 index ff085a34..00000000 --- a/src/modules/bmgd/agents/game-dev.agent.yaml +++ /dev/null @@ -1,53 +0,0 @@ -# Game Developer Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-dev.md" - name: Link Freeman - title: Game Developer - icon: ๐Ÿ•น๏ธ - module: bmgd - hasSidecar: false - - persona: - role: Senior Game Developer + Technical Implementation Specialist - identity: Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code. - communication_style: "Speaks like a speedrunner - direct, milestone-focused, always optimizing for the fastest path to ship" - principles: | - - 60fps is non-negotiable - - Write code designers can iterate without fear - - Ship early, ship often, iterate on player feedback - - Red-green-refactor: tests first, implementation second - - critical_actions: - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - "When running *dev-story, follow story acceptance criteria exactly and validate with tests" - - "Always check for performance implications on game loop code" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or check current sprint progress (optional)" - - - trigger: DS or fuzzy match on dev-story - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/dev-story/workflow.yaml" - description: "[DS] Execute Dev Story workflow, implementing tasks and tests" - - - trigger: CR or fuzzy match on code-review - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/code-review/workflow.yaml" - description: "[CR] Perform a thorough clean context QA code review on a story flagged Ready for Review" - - - trigger: QD or fuzzy match on quick-dev - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-dev/workflow.yaml" - description: "[QD] Flexible game development - implement features with game-specific considerations" - ide-only: true - - - trigger: QP or fuzzy match on quick-prototype - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-prototype/workflow.yaml" - description: "[QP] Rapid game prototyping - test mechanics and ideas quickly" - ide-only: true - - - trigger: AE or fuzzy match on advanced-elicitation - exec: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml" - description: "[AE] Advanced elicitation techniques to challenge the LLM to get better results" - web-only: true diff --git a/src/modules/bmgd/agents/game-qa.agent.yaml b/src/modules/bmgd/agents/game-qa.agent.yaml deleted file mode 100644 index 973d521c..00000000 --- a/src/modules/bmgd/agents/game-qa.agent.yaml +++ /dev/null @@ -1,67 +0,0 @@ -# Game QA Architect Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-qa.md" - name: GLaDOS - title: Game QA Architect - icon: ๐Ÿงช - module: bmgd - hasSidecar: false - - persona: - role: Game QA Architect + Test Automation Specialist - identity: Senior QA architect with 12+ years in game testing across Unity, Unreal, and Godot. Expert in automated testing frameworks, performance profiling, and shipping bug-free games on console, PC, and mobile. - communication_style: "Speaks like GLaDOS, the AI from Valve's 'Portal' series. Runs tests because we can. 'Trust, but verify with tests.'" - principles: | - - Test what matters: gameplay feel, performance, progression - - Automated tests catch regressions, humans catch fun problems - - Every shipped bug is a process failure, not a people failure - - Flaky tests are worse than no tests - they erode trust - - Profile before optimize, test before ship - - critical_actions: - - "Consult {project-root}/_bmad/bmgd/gametest/qa-index.csv to select knowledge fragments under knowledge/ and load only the files needed for the current task" - - "For E2E testing requests, always load knowledge/e2e-testing.md first" - - "When scaffolding tests, distinguish between unit, integration, and E2E test needs" - - "Load the referenced fragment(s) from {project-root}/_bmad/bmgd/gametest/knowledge/ before giving recommendations" - - "Cross-check recommendations with the current official Unity Test Framework, Unreal Automation, or Godot GUT documentation" - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or check current project state (optional)" - - - trigger: TF or fuzzy match on test-framework - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/test-framework/workflow.yaml" - description: "[TF] Initialize game test framework (Unity/Unreal/Godot)" - - - trigger: TD or fuzzy match on test-design - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/test-design/workflow.yaml" - description: "[TD] Create comprehensive game test scenarios" - - - trigger: TA or fuzzy match on test-automate - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/automate/workflow.yaml" - description: "[TA] Generate automated game tests" - - - trigger: ES or fuzzy match on e2e-scaffold - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/e2e-scaffold/workflow.yaml" - description: "[ES] Scaffold E2E testing infrastructure" - - - trigger: PP or fuzzy match on playtest-plan - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/playtest-plan/workflow.yaml" - description: "[PP] Create structured playtesting plan" - - - trigger: PT or fuzzy match on performance-test - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/performance/workflow.yaml" - description: "[PT] Design performance testing strategy" - - - trigger: TR or fuzzy match on test-review - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/test-review/workflow.yaml" - description: "[TR] Review test quality and coverage" - - - trigger: AE or fuzzy match on advanced-elicitation - exec: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml" - description: "[AE] Advanced elicitation techniques to challenge the LLM to get better results" - web-only: true diff --git a/src/modules/bmgd/agents/game-scrum-master.agent.yaml b/src/modules/bmgd/agents/game-scrum-master.agent.yaml deleted file mode 100644 index 1b2d599f..00000000 --- a/src/modules/bmgd/agents/game-scrum-master.agent.yaml +++ /dev/null @@ -1,60 +0,0 @@ -# Game Dev Scrum Master Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-scrum-master.md" - name: Max - title: Game Dev Scrum Master - icon: ๐ŸŽฏ - module: bmgd - hasSidecar: false - - persona: - role: Game Development Scrum Master + Sprint Orchestrator - identity: Certified Scrum Master specializing in game dev workflows. Expert at coordinating multi-disciplinary teams and translating GDDs into actionable stories. - communication_style: "Talks in game terminology - milestones are save points, handoffs are level transitions, blockers are boss fights" - principles: | - - Every sprint delivers playable increments - - Clean separation between design and implementation - - Keep the team moving through each phase - - Stories are single source of truth for implementation - - critical_actions: - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - "When running *create-story for game features, use GDD, Architecture, and Tech Spec to generate complete draft stories without elicitation, focusing on playable outcomes." - - "Generate complete story drafts from existing documentation without additional elicitation" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or initialize a workflow if not already done (optional)" - - - trigger: SP or fuzzy match on sprint-planning - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/sprint-planning/workflow.yaml" - description: "[SP] Generate or update sprint-status.yaml from epic files (Required after GDD+Epics are created)" - - - trigger: SS or fuzzy match on sprint-status - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/sprint-status/workflow.yaml" - description: "[SS] View sprint progress, surface risks, and get next action recommendation" - - - trigger: CS or fuzzy match on create-story - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/create-story/workflow.yaml" - description: "[CS] Create Story with direct ready-for-dev marking (Required to prepare stories for development)" - - - trigger: VS or fuzzy match on validate-story - validate-workflow: "{project-root}/_bmad/bmgd/workflows/4-production/create-story/workflow.yaml" - description: "[VS] Validate Story Draft with Independent Review (Highly Recommended)" - - - trigger: ER or fuzzy match on epic-retrospective - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/retrospective/workflow.yaml" - data: "{project-root}/_bmad/_config/agent-manifest.csv" - description: "[ER] Facilitate team retrospective after a game development epic is completed" - - - trigger: CC or fuzzy match on correct-course - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/correct-course/workflow.yaml" - description: "[CC] Navigate significant changes during game dev sprint (When implementation is off-track)" - - - trigger: AE or fuzzy match on advanced-elicitation - exec: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml" - description: "[AE] Advanced elicitation techniques to challenge the LLM to get better results" - web-only: true diff --git a/src/modules/bmgd/agents/game-solo-dev.agent.yaml b/src/modules/bmgd/agents/game-solo-dev.agent.yaml deleted file mode 100644 index 42df4c9f..00000000 --- a/src/modules/bmgd/agents/game-solo-dev.agent.yaml +++ /dev/null @@ -1,53 +0,0 @@ -# Game Solo Dev Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-solo-dev.md" - name: Indie - title: Game Solo Dev - icon: ๐ŸŽฎ - module: bmgd - hasSidecar: false - - persona: - role: Elite Indie Game Developer + Quick Flow Specialist - identity: Indie is a battle-hardened solo game developer who ships complete games from concept to launch. Expert in Unity, Unreal, and Godot, they've shipped titles across mobile, PC, and console. Lives and breathes the Quick Flow workflow - prototyping fast, iterating faster, and shipping before the hype dies. No team politics, no endless meetings - just pure, focused game development. - communication_style: "Direct, confident, and gameplay-focused. Uses dev slang, thinks in game feel and player experience. Every response moves the game closer to ship. 'Does it feel good? Ship it.'" - principles: | - - Prototype fast, fail fast, iterate faster. Quick Flow is the indie way. - - A playable build beats a perfect design doc. Ship early, playtest often. - - 60fps is non-negotiable. Performance is a feature. - - The core loop must be fun before anything else matters. - - critical_actions: - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or check current project state (optional)" - - - trigger: QP or fuzzy match on quick-prototype - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-prototype/workflow.yaml" - description: "[QP] Rapid prototype to test if the mechanic is fun (Start here for new ideas)" - - - trigger: QD or fuzzy match on quick-dev - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-dev/workflow.yaml" - description: "[QD] Implement features end-to-end solo with game-specific considerations" - - - trigger: TS or fuzzy match on tech-spec - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-spec/workflow.yaml" - description: "[TS] Architect a technical spec with implementation-ready stories" - - - trigger: CR or fuzzy match on code-review - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/code-review/workflow.yaml" - description: "[CR] Review code quality (use fresh context for best results)" - - - trigger: TF or fuzzy match on test-framework - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/test-framework/workflow.yaml" - description: "[TF] Set up automated testing for your game engine" - - - trigger: AE or fuzzy match on advanced-elicitation - exec: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml" - description: "[AE] Advanced elicitation techniques to challenge the LLM to get better results" - web-only: true diff --git a/src/modules/bmgd/gametest/knowledge/balance-testing.md b/src/modules/bmgd/gametest/knowledge/balance-testing.md deleted file mode 100644 index 9aad8ebf..00000000 --- a/src/modules/bmgd/gametest/knowledge/balance-testing.md +++ /dev/null @@ -1,220 +0,0 @@ -# Balance Testing for Games - -## Overview - -Balance testing validates that your game's systems create fair, engaging, and appropriately challenging experiences. It covers difficulty, economy, progression, and competitive balance. - -## Types of Balance - -### Difficulty Balance - -- Is the game appropriately challenging? -- Does difficulty progress smoothly? -- Are difficulty spikes intentional? - -### Economy Balance - -- Is currency earned at the right rate? -- Are prices fair for items/upgrades? -- Can the economy be exploited? - -### Progression Balance - -- Does power growth feel satisfying? -- Are unlocks paced well? -- Is there meaningful choice in builds? - -### Competitive Balance - -- Are all options viable? -- Is there a dominant strategy? -- Do counters exist for strong options? - -## Balance Testing Methods - -### Spreadsheet Modeling - -Before implementation, model systems mathematically: - -- DPS calculations -- Time-to-kill analysis -- Economy simulations -- Progression curves - -### Automated Simulation - -Run thousands of simulated games: - -- AI vs AI battles -- Economy simulations -- Progression modeling -- Monte Carlo analysis - -### Telemetry Analysis - -Gather data from real players: - -- Win rates by character/weapon/strategy -- Currency flow analysis -- Completion rates by level -- Time to reach milestones - -### Expert Testing - -High-skill players identify issues: - -- Exploits and degenerate strategies -- Underpowered options -- Skill ceiling concerns -- Meta predictions - -## Key Balance Metrics - -### Combat Balance - -| Metric | Target | Red Flag | -| ------------------------- | ------------------- | ------------------------- | -| Win rate (symmetric) | 50% | <45% or >55% | -| Win rate (asymmetric) | Varies by design | Outliers by >10% | -| Time-to-kill | Design dependent | Too fast = no counterplay | -| Damage dealt distribution | Even across options | One option dominates | - -### Economy Balance - -| Metric | Target | Red Flag | -| -------------------- | -------------------- | ------------------------------- | -| Currency earned/hour | Design dependent | Too fast = trivializes content | -| Item purchase rate | Healthy distribution | Nothing bought = bad prices | -| Currency on hand | Healthy churn | Hoarding = nothing worth buying | -| Premium currency | Reasonable value | Pay-to-win concerns | - -### Progression Balance - -| Metric | Target | Red Flag | -| ------------------ | ---------------------- | ---------------------- | -| Time to max level | Design dependent | Too fast = no journey | -| Power growth curve | Smooth, satisfying | Flat periods = boring | -| Build diversity | Multiple viable builds | One "best" build | -| Content completion | Healthy progression | Walls or trivial skips | - -## Balance Testing Process - -### 1. Define Design Intent - -- What experience are you creating? -- What should feel powerful? -- What trade-offs should exist? - -### 2. Model Before Building - -- Spreadsheet the math -- Simulate outcomes -- Identify potential issues - -### 3. Test Incrementally - -- Test each system in isolation -- Then test systems together -- Then test at scale - -### 4. Gather Data - -- Internal playtesting -- Telemetry from beta -- Expert feedback - -### 5. Iterate - -- Adjust based on data -- Re-test changes -- Document rationale - -## Common Balance Issues - -### Power Creep - -- **Symptom:** New content is always stronger -- **Cause:** Fear of releasing weak content -- **Fix:** Sidegrades over upgrades, periodic rebalancing - -### Dominant Strategy - -- **Symptom:** One approach beats all others -- **Cause:** Insufficient counters, math oversight -- **Fix:** Add counters, nerf dominant option, buff alternatives - -### Feast or Famine - -- **Symptom:** Players either crush or get crushed -- **Cause:** Snowball mechanics, high variance -- **Fix:** Comeback mechanics, reduce variance - -### Analysis Paralysis - -- **Symptom:** Too many options, players can't choose -- **Cause:** Over-complicated systems -- **Fix:** Simplify, provide recommendations - -## Balance Tools - -### Spreadsheets - -- Model DPS, TTK, economy -- Simulate progression -- Compare options side-by-side - -### Simulation Frameworks - -- Monte Carlo for variance -- AI bots for combat testing -- Economy simulations - -### Telemetry Systems - -- Track player choices -- Measure outcomes -- A/B test changes - -### Visualization - -- Graphs of win rates over time -- Heat maps of player deaths -- Flow charts of progression - -## Balance Testing Checklist - -### Pre-Launch - -- [ ] Core systems modeled in spreadsheets -- [ ] Internal playtesting complete -- [ ] No obvious dominant strategies -- [ ] Difficulty curve feels right -- [ ] Economy tested for exploits -- [ ] Progression pacing validated - -### Live Service - -- [ ] Telemetry tracking key metrics -- [ ] Regular balance reviews scheduled -- [ ] Player feedback channels monitored -- [ ] Hotfix process for critical issues -- [ ] Communication plan for changes - -## Communicating Balance Changes - -### Patch Notes Best Practices - -- Explain the "why" not just the "what" -- Use concrete numbers when possible -- Acknowledge player concerns -- Set expectations for future changes - -### Example - -``` -**Sword of Valor - Damage reduced from 100 to 85** -Win rate for Sword users was 58%, indicating it was -overperforming. This brings it in line with other weapons -while maintaining its identity as a high-damage option. -We'll continue monitoring and adjust if needed. -``` diff --git a/src/modules/bmgd/gametest/knowledge/certification-testing.md b/src/modules/bmgd/gametest/knowledge/certification-testing.md deleted file mode 100644 index 4e268f8d..00000000 --- a/src/modules/bmgd/gametest/knowledge/certification-testing.md +++ /dev/null @@ -1,319 +0,0 @@ -# Platform Certification Testing Guide - -## Overview - -Certification testing ensures games meet platform holder requirements (Sony TRC, Microsoft XR, Nintendo Guidelines). Failing certification delays launch and costs moneyโ€”test thoroughly before submission. - -## Platform Requirements Overview - -### Major Platforms - -| Platform | Requirements Doc | Submission Portal | -| --------------- | -------------------------------------- | ------------------------- | -| PlayStation | TRC (Technical Requirements Checklist) | PlayStation Partners | -| Xbox | XR (Xbox Requirements) | Xbox Partner Center | -| Nintendo Switch | Guidelines | Nintendo Developer Portal | -| Steam | Guidelines (less strict) | Steamworks | -| iOS | App Store Guidelines | App Store Connect | -| Android | Play Store Policies | Google Play Console | - -## Common Certification Categories - -### Account and User Management - -``` -REQUIREMENT: User Switching - GIVEN user is playing game - WHEN system-level user switch occurs - THEN game handles transition gracefully - AND no data corruption - AND correct user data loads - -REQUIREMENT: Guest Accounts - GIVEN guest user plays game - WHEN guest makes progress - THEN progress is not saved to other accounts - AND appropriate warnings displayed - -REQUIREMENT: Parental Controls - GIVEN parental controls restrict content - WHEN restricted content is accessed - THEN content is blocked or modified - AND appropriate messaging shown -``` - -### System Events - -``` -REQUIREMENT: Suspend/Resume (PS4/PS5) - GIVEN game is running - WHEN console enters rest mode - AND console wakes from rest mode - THEN game resumes correctly - AND network reconnects if needed - AND no audio/visual glitches - -REQUIREMENT: Controller Disconnect - GIVEN player is in gameplay - WHEN controller battery dies - THEN game pauses immediately - AND reconnect prompt appears - AND gameplay resumes when connected - -REQUIREMENT: Storage Full - GIVEN storage is nearly full - WHEN game attempts save - THEN graceful error handling - AND user informed of issue - AND no data corruption -``` - -### Network Requirements - -``` -REQUIREMENT: PSN/Xbox Live Unavailable - GIVEN online features - WHEN platform network is unavailable - THEN offline features still work - AND appropriate error messages - AND no crashes - -REQUIREMENT: Network Transition - GIVEN active online session - WHEN network connection lost - THEN graceful handling - AND reconnection attempted - AND user informed of status - -REQUIREMENT: NAT Type Handling - GIVEN various NAT configurations - WHEN multiplayer is attempted - THEN appropriate feedback on connectivity - AND fallback options offered -``` - -### Save Data - -``` -REQUIREMENT: Save Data Integrity - GIVEN save data exists - WHEN save is loaded - THEN data is validated - AND corrupted data handled gracefully - AND no crashes on invalid data - -REQUIREMENT: Cloud Save Sync - GIVEN cloud saves enabled - WHEN save conflict occurs - THEN user chooses which to keep - AND no silent data loss - -REQUIREMENT: Save Data Portability (PS4โ†’PS5) - GIVEN save from previous generation - WHEN loaded on current generation - THEN data migrates correctly - AND no features lost -``` - -## Platform-Specific Requirements - -### PlayStation (TRC) - -| Requirement | Description | Priority | -| ----------- | --------------------------- | -------- | -| TRC R4010 | Suspend/resume handling | Critical | -| TRC R4037 | User switching | Critical | -| TRC R4062 | Parental controls | Critical | -| TRC R4103 | PS VR comfort ratings | VR only | -| TRC R4120 | DualSense haptics standards | PS5 | -| TRC R5102 | PSN sign-in requirements | Online | - -### Xbox (XR) - -| Requirement | Description | Priority | -| ----------- | ----------------------------- | ----------- | -| XR-015 | Title timeout handling | Critical | -| XR-045 | User sign-out handling | Critical | -| XR-067 | Active user requirement | Critical | -| XR-074 | Quick Resume support | Series X/S | -| XR-115 | Xbox Accessibility Guidelines | Recommended | - -### Nintendo Switch - -| Requirement | Description | Priority | -| ------------------ | ------------------- | -------- | -| Docked/Handheld | Seamless transition | Critical | -| Joy-Con detachment | Controller handling | Critical | -| Home button | Immediate response | Critical | -| Screenshots/Video | Proper support | Required | -| Sleep mode | Resume correctly | Critical | - -## Automated Test Examples - -### System Event Testing - -```cpp -// Unreal - Suspend/Resume Test -IMPLEMENT_SIMPLE_AUTOMATION_TEST( - FSuspendResumeTest, - "Certification.System.SuspendResume", - EAutomationTestFlags::ApplicationContextMask | EAutomationTestFlags::ProductFilter -) - -bool FSuspendResumeTest::RunTest(const FString& Parameters) -{ - // Get game state before suspend - FGameState StateBefore = GetCurrentGameState(); - - // Simulate suspend - FCoreDelegates::ApplicationWillEnterBackgroundDelegate.Broadcast(); - - // Simulate resume - FCoreDelegates::ApplicationHasEnteredForegroundDelegate.Broadcast(); - - // Verify state matches - FGameState StateAfter = GetCurrentGameState(); - - TestEqual("Player position preserved", - StateAfter.PlayerPosition, StateBefore.PlayerPosition); - TestEqual("Game progress preserved", - StateAfter.Progress, StateBefore.Progress); - - return true; -} -``` - -```csharp -// Unity - Controller Disconnect Test -[UnityTest] -public IEnumerator ControllerDisconnect_ShowsPauseMenu() -{ - // Simulate gameplay - GameManager.Instance.StartGame(); - yield return new WaitForSeconds(1f); - - // Simulate controller disconnect - InputSystem.DisconnectDevice(Gamepad.current); - yield return null; - - // Verify pause menu shown - Assert.IsTrue(PauseMenu.IsVisible, "Pause menu should appear"); - Assert.IsTrue(Time.timeScale == 0, "Game should be paused"); - - // Simulate reconnect - InputSystem.ReconnectDevice(Gamepad.current); - yield return null; - - // Verify prompt appears - Assert.IsTrue(ReconnectPrompt.IsVisible); -} -``` - -```gdscript -# Godot - Save Corruption Test -func test_corrupted_save_handling(): - # Create corrupted save file - var file = FileAccess.open("user://save_corrupt.dat", FileAccess.WRITE) - file.store_string("CORRUPTED_GARBAGE_DATA") - file.close() - - # Attempt to load - var result = SaveManager.load("save_corrupt") - - # Should handle gracefully - assert_null(result, "Should return null for corrupted save") - assert_false(OS.has_feature("crashed"), "Should not crash") - - # Should show user message - var message_shown = ErrorDisplay.current_message != "" - assert_true(message_shown, "Should inform user of corruption") -``` - -## Pre-Submission Checklist - -### General Requirements - -- [ ] Game boots to interactive state within platform time limit -- [ ] Controller disconnect pauses game -- [ ] User sign-out handled correctly -- [ ] Save data validates on load -- [ ] No crashes in 8+ hours of automated testing -- [ ] Memory usage within platform limits -- [ ] Load times meet requirements - -### Platform Services - -- [ ] Achievements/Trophies work correctly -- [ ] Friends list integration works -- [ ] Invite system functions -- [ ] Store/DLC integration validated -- [ ] Cloud saves sync properly - -### Accessibility (Increasingly Required) - -- [ ] Text size options -- [ ] Colorblind modes -- [ ] Subtitle options -- [ ] Controller remapping -- [ ] Screen reader support (where applicable) - -### Content Compliance - -- [ ] Age rating displayed correctly -- [ ] Parental controls respected -- [ ] No prohibited content -- [ ] Required legal text present - -## Common Certification Failures - -| Issue | Platform | Fix | -| --------------------- | ------------ | ----------------------------------- | -| Home button delay | All consoles | Respond within required time | -| Controller timeout | PlayStation | Handle reactivation properly | -| Save on suspend | PlayStation | Don't save during suspend | -| User context loss | Xbox | Track active user correctly | -| Joy-Con drift | Switch | Proper deadzone handling | -| Background memory | Mobile | Release resources when backgrounded | -| Crash on corrupt data | All | Validate all loaded data | - -## Testing Matrix - -### Build Configurations to Test - -| Configuration | Scenarios | -| --------------- | ----------------------- | -| First boot | No save data exists | -| Return user | Save data present | -| Upgrade path | Previous version save | -| Fresh install | After uninstall | -| Low storage | Minimum space available | -| Network offline | No connectivity | - -### Hardware Variants - -| Platform | Variants to Test | -| ----------- | ------------------------------- | -| PlayStation | PS4, PS4 Pro, PS5 | -| Xbox | One, One X, Series S, Series X | -| Switch | Docked, Handheld, Lite | -| PC | Min spec, recommended, high-end | - -## Best Practices - -### DO - -- Read platform requirements document thoroughly -- Test on actual hardware, not just dev kits -- Automate certification test scenarios -- Submit with extra time for re-submission -- Document all edge case handling -- Test with real user accounts - -### DON'T - -- Assume debug builds behave like retail -- Skip testing on oldest supported hardware -- Ignore platform-specific features -- Wait until last minute to test certification items -- Use placeholder content in submission build -- Skip testing with real platform services diff --git a/src/modules/bmgd/gametest/knowledge/compatibility-testing.md b/src/modules/bmgd/gametest/knowledge/compatibility-testing.md deleted file mode 100644 index 291bdfce..00000000 --- a/src/modules/bmgd/gametest/knowledge/compatibility-testing.md +++ /dev/null @@ -1,228 +0,0 @@ -# Compatibility Testing for Games - -## Overview - -Compatibility testing ensures your game works correctly across different hardware, operating systems, and configurations that players use. - -## Types of Compatibility Testing - -### Hardware Compatibility - -- Graphics cards (NVIDIA, AMD, Intel) -- CPUs (Intel, AMD, Apple Silicon) -- Memory configurations -- Storage types (HDD, SSD, NVMe) -- Input devices (controllers, keyboards, mice) - -### Software Compatibility - -- Operating system versions -- Driver versions -- Background software conflicts -- Antivirus interference - -### Platform Compatibility - -- Console SKUs (PS5, Xbox Series X|S) -- PC storefronts (Steam, Epic, GOG) -- Mobile devices (iOS, Android) -- Cloud gaming services - -### Configuration Compatibility - -- Graphics settings combinations -- Resolution and aspect ratios -- Refresh rates (60Hz, 144Hz, etc.) -- HDR and color profiles - -## Testing Matrix - -### Minimum Hardware Matrix - -| Component | Budget | Mid-Range | High-End | -| --------- | -------- | --------- | -------- | -| GPU | GTX 1050 | RTX 3060 | RTX 4080 | -| CPU | i5-6400 | i7-10700 | i9-13900 | -| RAM | 8GB | 16GB | 32GB | -| Storage | HDD | SATA SSD | NVMe | - -### OS Matrix - -- Windows 10 (21H2, 22H2) -- Windows 11 (22H2, 23H2) -- macOS (Ventura, Sonoma) -- Linux (Ubuntu LTS, SteamOS) - -### Controller Matrix - -- Xbox Controller (wired, wireless, Elite) -- PlayStation DualSense -- Nintendo Pro Controller -- Generic XInput controllers -- Keyboard + Mouse - -## Testing Approach - -### 1. Define Supported Configurations - -- Minimum specifications -- Recommended specifications -- Officially supported platforms -- Known unsupported configurations - -### 2. Create Test Matrix - -- Prioritize common configurations -- Include edge cases -- Balance coverage vs. effort - -### 3. Execute Systematic Testing - -- Full playthrough on key configs -- Spot checks on edge cases -- Automated smoke tests where possible - -### 4. Document Issues - -- Repro steps with exact configuration -- Severity and frequency -- Workarounds if available - -## Common Compatibility Issues - -### Graphics Issues - -| Issue | Cause | Detection | -| -------------------- | ---------------------- | -------------------------------- | -| Crashes on launch | Driver incompatibility | Test on multiple GPUs | -| Rendering artifacts | Shader issues | Visual inspection across configs | -| Performance variance | Optimization gaps | Profile on multiple GPUs | -| Resolution bugs | Aspect ratio handling | Test non-standard resolutions | - -### Input Issues - -| Issue | Cause | Detection | -| ----------------------- | ------------------ | ------------------------------ | -| Controller not detected | Missing driver/API | Test all supported controllers | -| Wrong button prompts | Platform detection | Swap controllers mid-game | -| Stick drift handling | Deadzone issues | Test worn controllers | -| Mouse acceleration | Raw input issues | Test at different DPIs | - -### Audio Issues - -| Issue | Cause | Detection | -| -------------- | ---------------- | --------------------------- | -| No sound | Device selection | Test multiple audio devices | -| Crackling | Buffer issues | Test under CPU load | -| Wrong channels | Surround setup | Test stereo vs 5.1 vs 7.1 | - -## Platform-Specific Considerations - -### PC - -- **Steam:** Verify Steam Input, Steamworks features -- **Epic:** Test EOS features if used -- **GOG:** Test offline/DRM-free functionality -- **Game Pass:** Test Xbox services integration - -### Console - -- **Certification Requirements:** Study TRCs/XRs early -- **SKU Differences:** Test on all variants (S vs X) -- **External Storage:** Test on USB drives -- **Quick Resume:** Test suspend/resume cycles - -### Mobile - -- **Device Fragmentation:** Test across screen sizes -- **OS Versions:** Test min supported to latest -- **Permissions:** Test permission flows -- **App Lifecycle:** Test background/foreground - -## Automated Compatibility Testing - -### Smoke Tests - -```yaml -# Run on matrix of configurations -compatibility_test: - matrix: - os: [windows-10, windows-11, ubuntu-22] - gpu: [nvidia, amd, intel] - script: - - launch_game --headless - - verify_main_menu_reached - - check_no_errors -``` - -### Screenshot Comparison - -- Capture screenshots on different GPUs -- Compare for rendering differences -- Flag significant deviations - -### Cloud Testing Services - -- AWS Device Farm -- BrowserStack (web games) -- LambdaTest -- Sauce Labs - -## Compatibility Checklist - -### Pre-Alpha - -- [ ] Minimum specs defined -- [ ] Key platforms identified -- [ ] Test matrix created -- [ ] Test hardware acquired/rented - -### Alpha - -- [ ] Full playthrough on min spec -- [ ] Controller support verified -- [ ] Major graphics issues found -- [ ] Platform SDK integrated - -### Beta - -- [ ] All matrix configurations tested -- [ ] Edge cases explored -- [ ] Certification pre-check done -- [ ] Store page requirements met - -### Release - -- [ ] Final certification passed -- [ ] Known issues documented -- [ ] Workarounds communicated -- [ ] Support matrix published - -## Documenting Compatibility - -### System Requirements - -``` -MINIMUM: -- OS: Windows 10 64-bit -- Processor: Intel Core i5-6400 or AMD equivalent -- Memory: 8 GB RAM -- Graphics: NVIDIA GTX 1050 or AMD RX 560 -- Storage: 50 GB available space - -RECOMMENDED: -- OS: Windows 11 64-bit -- Processor: Intel Core i7-10700 or AMD equivalent -- Memory: 16 GB RAM -- Graphics: NVIDIA RTX 3060 or AMD RX 6700 XT -- Storage: 50 GB SSD -``` - -### Known Issues - -Maintain a public-facing list of known compatibility issues with: - -- Affected configurations -- Symptoms -- Workarounds -- Fix status diff --git a/src/modules/bmgd/gametest/knowledge/e2e-testing.md b/src/modules/bmgd/gametest/knowledge/e2e-testing.md deleted file mode 100644 index 8f35bcd7..00000000 --- a/src/modules/bmgd/gametest/knowledge/e2e-testing.md +++ /dev/null @@ -1,1013 +0,0 @@ -# End-to-End Testing for Games - -## Overview - -E2E tests validate complete gameplay flows from the player's perspective โ€” the full orchestra, not individual instruments. Unlike integration tests that verify system interactions, E2E tests verify *player journeys* work correctly from start to finish. - -This is the difference between "does the damage calculator work with the inventory system?" (integration) and "can a player actually complete a combat encounter from selection to resolution?" (E2E). - -## E2E vs Integration vs Unit - -| Aspect | Unit | Integration | E2E | -|--------|------|-------------|-----| -| Scope | Single class | System interaction | Complete flow | -| Speed | < 10ms | < 1s | 1-30s | -| Stability | Very stable | Stable | Requires care | -| Example | DamageCalc math | Combat + Inventory | Full combat encounter | -| Dependencies | None/mocked | Some real | All real | -| Catches | Logic bugs | Wiring bugs | Journey bugs | - -## The E2E Testing Pyramid Addition - -``` - /\ - / \ Manual Playtesting - /----\ (Fun, Feel, Experience) - / \ - /--------\ E2E Tests - / \ (Player Journeys) - /------------\ - / \ Integration Tests - /----------------\ (System Interactions) - / \ Unit Tests - /____________________\ (Pure Logic) -``` - -E2E tests sit between integration tests and manual playtesting. They automate what *can* be automated about player experience while acknowledging that "is this fun?" still requires human judgment. - -## E2E Infrastructure Requirements - -Before writing E2E tests, scaffold supporting infrastructure. Without this foundation, E2E tests become brittle, flaky nightmares that erode trust faster than they build confidence. - -### 1. Test Fixture Base Class - -Provides scene loading, cleanup, and common utilities. Every E2E test inherits from this. - -**Unity Example:** - -```csharp -using System.Collections; -using NUnit.Framework; -using UnityEngine; -using UnityEngine.SceneManagement; -using UnityEngine.TestTools; - -public abstract class GameE2ETestFixture -{ - protected virtual string SceneName => "GameScene"; - protected GameStateManager GameState { get; private set; } - protected InputSimulator Input { get; private set; } - protected ScenarioBuilder Scenario { get; private set; } - - [UnitySetUp] - public IEnumerator BaseSetUp() - { - // Load the game scene - yield return SceneManager.LoadSceneAsync(SceneName); - yield return null; // Wait one frame for scene initialization - - // Get core references - GameState = Object.FindFirstObjectByType(); - Assert.IsNotNull(GameState, $"GameStateManager not found in {SceneName}"); - - // Initialize test utilities - Input = new InputSimulator(); - Scenario = new ScenarioBuilder(GameState); - - // Wait for game to be ready - yield return WaitForGameReady(); - } - - [UnityTearDown] - public IEnumerator BaseTearDown() - { - // Clean up any test-spawned objects - yield return CleanupTestObjects(); - - // Reset input state - Input?.Reset(); - } - - protected IEnumerator WaitForGameReady(float timeout = 10f) - { - yield return AsyncAssert.WaitUntil( - () => GameState != null && GameState.IsReady, - "Game ready state", - timeout); - } - - protected virtual IEnumerator CleanupTestObjects() - { - // Override in derived classes for game-specific cleanup - yield return null; - } -} -``` - -**Unreal Example:** - -```cpp -// GameE2ETestBase.h -UCLASS() -class AGameE2ETestBase : public AFunctionalTest -{ - GENERATED_BODY() - -protected: - UPROPERTY() - UGameStateManager* GameState; - - UPROPERTY() - UInputSimulator* InputSim; - - UPROPERTY() - UScenarioBuilder* Scenario; - - virtual void PrepareTest() override; - virtual void StartTest() override; - virtual void CleanUp() override; - - void WaitForGameReady(float Timeout = 10.f); -}; -``` - -**Godot Example:** - -```gdscript -extends GutTest -class_name GameE2ETestFixture - -var game_state: GameStateManager -var input_sim: InputSimulator -var scenario: ScenarioBuilder -var _scene_instance: Node - -func before_each(): - # Load game scene - var scene = load("res://scenes/game.tscn") - _scene_instance = scene.instantiate() - add_child(_scene_instance) - - # Get references - game_state = _scene_instance.get_node("GameStateManager") - input_sim = InputSimulator.new() - scenario = ScenarioBuilder.new(game_state) - - # Wait for ready - await wait_for_game_ready() - -func after_each(): - if _scene_instance: - _scene_instance.queue_free() - input_sim = null - scenario = null - -func wait_for_game_ready(timeout: float = 10.0): - var elapsed = 0.0 - while not game_state.is_ready and elapsed < timeout: - await get_tree().process_frame - elapsed += get_process_delta_time() - assert_true(game_state.is_ready, "Game should be ready") -``` - -### 2. Scenario Builder (Fluent API) - -Configure game state for test scenarios without manual setup. This is the secret sauce โ€” it lets you express test preconditions in domain language. - -**Unity Example:** - -```csharp -public class ScenarioBuilder -{ - private readonly GameStateManager _gameState; - private readonly List> _setupActions = new(); - - public ScenarioBuilder(GameStateManager gameState) - { - _gameState = gameState; - } - - // Domain-specific setup methods - public ScenarioBuilder WithUnit(Faction faction, Hex position, int movementPoints = 6) - { - _setupActions.Add(() => SpawnUnit(faction, position, movementPoints)); - return this; - } - - public ScenarioBuilder WithTerrain(Hex position, TerrainType terrain) - { - _setupActions.Add(() => SetTerrain(position, terrain)); - return this; - } - - public ScenarioBuilder OnTurn(int turnNumber) - { - _setupActions.Add(() => SetTurn(turnNumber)); - return this; - } - - public ScenarioBuilder OnPhase(TurnPhase phase) - { - _setupActions.Add(() => SetPhase(phase)); - return this; - } - - public ScenarioBuilder WithActiveFaction(Faction faction) - { - _setupActions.Add(() => SetActiveFaction(faction)); - return this; - } - - public ScenarioBuilder FromSaveFile(string saveFileName) - { - _setupActions.Add(() => LoadSaveFile(saveFileName)); - return this; - } - - // Execute all setup actions - public IEnumerator Build() - { - foreach (var action in _setupActions) - { - yield return action(); - yield return null; // Allow state to propagate - } - _setupActions.Clear(); - } - - // Private implementation methods - private IEnumerator SpawnUnit(Faction faction, Hex position, int mp) - { - var unit = _gameState.SpawnUnit(faction, position); - unit.MovementPoints = mp; - yield return null; - } - - private IEnumerator SetTerrain(Hex position, TerrainType terrain) - { - _gameState.Map.SetTerrain(position, terrain); - yield return null; - } - - private IEnumerator SetTurn(int turn) - { - _gameState.SetTurnNumber(turn); - yield return null; - } - - private IEnumerator SetPhase(TurnPhase phase) - { - _gameState.SetPhase(phase); - yield return null; - } - - private IEnumerator SetActiveFaction(Faction faction) - { - _gameState.SetActiveFaction(faction); - yield return null; - } - - private IEnumerator LoadSaveFile(string fileName) - { - var path = $"TestData/{fileName}"; - yield return _gameState.LoadGame(path); - } -} -``` - -**Usage:** - -```csharp -yield return Scenario - .WithUnit(Faction.Player, new Hex(3, 4), movementPoints: 6) - .WithUnit(Faction.Enemy, new Hex(5, 4)) - .WithTerrain(new Hex(4, 4), TerrainType.Forest) - .OnTurn(1) - .WithActiveFaction(Faction.Player) - .Build(); -``` - -### 3. Input Simulator - -Abstract player input for deterministic testing. Don't simulate raw mouse positions โ€” simulate player *intent*. - -**Unity Example (New Input System):** - -```csharp -using UnityEngine; -using UnityEngine.InputSystem; - -public class InputSimulator -{ - private Mouse _mouse; - private Keyboard _keyboard; - private Camera _camera; - - public InputSimulator() - { - _mouse = Mouse.current ?? InputSystem.AddDevice(); - _keyboard = Keyboard.current ?? InputSystem.AddDevice(); - _camera = Camera.main; - } - - public IEnumerator ClickWorldPosition(Vector3 worldPos) - { - var screenPos = _camera.WorldToScreenPoint(worldPos); - yield return ClickScreenPosition(screenPos); - } - - public IEnumerator ClickHex(Hex hex) - { - var worldPos = HexUtils.HexToWorld(hex); - yield return ClickWorldPosition(worldPos); - } - - public IEnumerator ClickScreenPosition(Vector2 screenPos) - { - // Move mouse - InputSystem.QueueStateEvent(_mouse, new MouseState { position = screenPos }); - yield return null; - - // Press - InputSystem.QueueStateEvent(_mouse, new MouseState - { - position = screenPos, - buttons = 1 - }); - yield return null; - - // Release - InputSystem.QueueStateEvent(_mouse, new MouseState - { - position = screenPos, - buttons = 0 - }); - yield return null; - } - - public IEnumerator ClickButton(string buttonName) - { - var button = GameObject.Find(buttonName)?.GetComponent(); - Assert.IsNotNull(button, $"Button '{buttonName}' not found"); - - button.onClick.Invoke(); - yield return null; - } - - public IEnumerator DragFromTo(Vector3 from, Vector3 to, float duration = 0.5f) - { - var fromScreen = _camera.WorldToScreenPoint(from); - var toScreen = _camera.WorldToScreenPoint(to); - - // Start drag - InputSystem.QueueStateEvent(_mouse, new MouseState - { - position = fromScreen, - buttons = 1 - }); - yield return null; - - // Interpolate drag - var elapsed = 0f; - while (elapsed < duration) - { - var t = elapsed / duration; - var pos = Vector2.Lerp(fromScreen, toScreen, t); - InputSystem.QueueStateEvent(_mouse, new MouseState - { - position = pos, - buttons = 1 - }); - yield return null; - elapsed += Time.deltaTime; - } - - // End drag - InputSystem.QueueStateEvent(_mouse, new MouseState - { - position = toScreen, - buttons = 0 - }); - yield return null; - } - - public IEnumerator PressKey(Key key) - { - _keyboard.SetKeyDown(key); - yield return null; - _keyboard.SetKeyUp(key); - yield return null; - } - - public void Reset() - { - // Reset any held state - if (_mouse != null) - { - InputSystem.QueueStateEvent(_mouse, new MouseState()); - } - } -} -``` - -### 4. Async Assertions - -Wait-for-condition assertions with meaningful failure messages. The timeout and message are critical โ€” when tests fail, you need to know *what* it was waiting for. - -**Unity Example:** - -```csharp -using System; -using System.Collections; -using NUnit.Framework; -using UnityEngine; - -public static class AsyncAssert -{ - /// - /// Wait until condition is true, or fail with message after timeout. - /// - public static IEnumerator WaitUntil( - Func condition, - string description, - float timeout = 5f) - { - var elapsed = 0f; - while (!condition() && elapsed < timeout) - { - yield return null; - elapsed += Time.deltaTime; - } - - Assert.IsTrue(condition(), - $"Timeout after {timeout}s waiting for: {description}"); - } - - /// - /// Wait until condition is true, with periodic logging. - /// - public static IEnumerator WaitUntilVerbose( - Func condition, - string description, - float timeout = 5f, - float logInterval = 1f) - { - var elapsed = 0f; - var lastLog = 0f; - - while (!condition() && elapsed < timeout) - { - if (elapsed - lastLog >= logInterval) - { - Debug.Log($"[E2E] Still waiting for: {description} ({elapsed:F1}s)"); - lastLog = elapsed; - } - yield return null; - elapsed += Time.deltaTime; - } - - Assert.IsTrue(condition(), - $"Timeout after {timeout}s waiting for: {description}"); - } - - /// - /// Wait for a specific value, with descriptive failure. - /// Note: For floating-point comparisons, use WaitForValueApprox instead - /// to handle precision issues. This method uses exact equality. - /// - public static IEnumerator WaitForValue( - Func getter, - T expected, - string description, - float timeout = 5f) where T : IEquatable - { - yield return WaitUntil( - () => expected.Equals(getter()), - $"{description} to equal {expected} (current: {getter()})", - timeout); - } - - /// - /// Wait for a float value within tolerance (handles floating-point precision). - /// - public static IEnumerator WaitForValueApprox( - Func getter, - float expected, - string description, - float tolerance = 0.0001f, - float timeout = 5f) - { - yield return WaitUntil( - () => Mathf.Abs(expected - getter()) < tolerance, - $"{description} to equal ~{expected} ยฑ{tolerance} (current: {getter()})", - timeout); - } - - /// - /// Wait for a double value within tolerance (handles floating-point precision). - /// - public static IEnumerator WaitForValueApprox( - Func getter, - double expected, - string description, - double tolerance = 0.0001, - float timeout = 5f) - { - yield return WaitUntil( - () => Math.Abs(expected - getter()) < tolerance, - $"{description} to equal ~{expected} ยฑ{tolerance} (current: {getter()})", - timeout); - } - - /// - /// Wait for an event to fire. - /// - public static IEnumerator WaitForEvent( - Action> subscribe, - Action> unsubscribe, - string eventName, - float timeout = 5f) where T : class - { - T received = null; - Action handler = e => received = e; - - subscribe(handler); - - yield return WaitUntil( - () => received != null, - $"Event '{eventName}' to fire", - timeout); - - unsubscribe(handler); - } - - /// - /// Assert that something does NOT happen within a time window. - /// - public static IEnumerator WaitAndAssertNot( - Func condition, - string description, - float duration = 1f) - { - var elapsed = 0f; - while (elapsed < duration) - { - Assert.IsFalse(condition(), - $"Condition unexpectedly became true: {description}"); - yield return null; - elapsed += Time.deltaTime; - } - } -} -``` - -## E2E Test Patterns - -### Given-When-Then with Async - -The core pattern for E2E tests. Clear structure, readable intent. - -```csharp -[UnityTest] -public IEnumerator PlayerCanMoveUnitThroughZOC() -{ - // GIVEN: Soviet unit adjacent to German ZOC - yield return Scenario - .WithUnit(Faction.Soviet, new Hex(3, 4), movementPoints: 6) - .WithUnit(Faction.German, new Hex(4, 4)) // Creates ZOC at adjacent hexes - .WithActiveFaction(Faction.Soviet) - .Build(); - - // WHEN: Player selects unit and moves through ZOC - yield return Input.ClickHex(new Hex(3, 4)); // Select unit - yield return AsyncAssert.WaitUntil( - () => GameState.Selection.HasSelectedUnit, - "Unit should be selected"); - - yield return Input.ClickHex(new Hex(5, 4)); // Click destination (through ZOC) - - // THEN: Unit arrives with reduced movement points (ZOC cost) - yield return AsyncAssert.WaitUntil( - () => GetUnitAt(new Hex(5, 4)) != null, - "Unit should arrive at destination"); - - var unit = GetUnitAt(new Hex(5, 4)); - Assert.Less(unit.MovementPoints, 3, - "ZOC passage should cost extra movement points"); -} -``` - -### Full Turn Cycle - -Testing the complete turn lifecycle. - -```csharp -[UnityTest] -public IEnumerator FullTurnCycle_PlayerToAIAndBack() -{ - // GIVEN: Mid-game state with both factions having units - yield return Scenario - .FromSaveFile("mid_game_scenario.json") - .Build(); - - var startingTurn = GameState.TurnNumber; - - // WHEN: Player ends their turn - yield return Input.ClickButton("EndPhaseButton"); - yield return AsyncAssert.WaitUntil( - () => GameState.CurrentPhase == TurnPhase.EndPhaseConfirmation, - "End phase confirmation"); - - yield return Input.ClickButton("ConfirmButton"); - - // THEN: AI executes its turn - yield return AsyncAssert.WaitUntil( - () => GameState.CurrentFaction == Faction.AI, - "AI turn should begin"); - - // AND: Eventually returns to player - yield return AsyncAssert.WaitUntil( - () => GameState.CurrentFaction == Faction.Player, - "Player turn should return", - timeout: 30f); // AI might take a while - - Assert.AreEqual(startingTurn + 1, GameState.TurnNumber, - "Turn number should increment"); -} -``` - -### Save/Load Round-Trip - -Critical for any game with persistence. - -```csharp -[UnityTest] -public IEnumerator SaveLoad_PreservesGameState() -{ - // GIVEN: Game in specific state - yield return Scenario - .WithUnit(Faction.Player, new Hex(5, 5), movementPoints: 3) - .OnTurn(7) - .Build(); - - var unitPosition = new Hex(5, 5); - var originalMP = GetUnitAt(unitPosition).MovementPoints; - var originalTurn = GameState.TurnNumber; - - // WHEN: Save and reload - var savePath = "test_save_roundtrip"; - yield return GameState.SaveGame(savePath); - - // Trash the current state - yield return SceneManager.LoadSceneAsync(SceneName); - yield return WaitForGameReady(); - - // Load the save - yield return GameState.LoadGame(savePath); - yield return WaitForGameReady(); - - // THEN: State is preserved - Assert.AreEqual(originalTurn, GameState.TurnNumber, - "Turn number should be preserved"); - - var loadedUnit = GetUnitAt(unitPosition); - Assert.IsNotNull(loadedUnit, "Unit should exist at saved position"); - Assert.AreEqual(originalMP, loadedUnit.MovementPoints, - "Movement points should be preserved"); - - // Cleanup - var savedFilePath = GameState.GetSavePath(savePath); - if (System.IO.File.Exists(savedFilePath)) - { - try - { - System.IO.File.Delete(savedFilePath); - } - catch (System.IO.IOException ex) - { - Debug.LogWarning($"[E2E] Failed to delete test save file '{savedFilePath}': {ex.Message}"); - } - catch (UnauthorizedAccessException ex) - { - Debug.LogWarning($"[E2E] Access denied deleting test save file '{savedFilePath}': {ex.Message}"); - } - } -} -``` - -### UI Flow Testing - -Testing complete UI journeys. - -```csharp -[UnityTest] -public IEnumerator MainMenu_NewGame_ReachesGameplay() -{ - // GIVEN: At main menu - yield return SceneManager.LoadSceneAsync("MainMenu"); - yield return null; - - // WHEN: Start new game flow - yield return Input.ClickButton("NewGameButton"); - yield return AsyncAssert.WaitUntil( - () => FindPanel("DifficultySelect") != null, - "Difficulty selection should appear"); - - yield return Input.ClickButton("NormalDifficultyButton"); - yield return Input.ClickButton("StartButton"); - - // THEN: Game scene loads and is playable - yield return AsyncAssert.WaitUntil( - () => SceneManager.GetActiveScene().name == "GameScene", - "Game scene should load", - timeout: 10f); - - yield return WaitForGameReady(); - - Assert.AreEqual(TurnPhase.PlayerMovement, GameState.CurrentPhase, - "Should start in player movement phase"); -} -``` - -## What to E2E Test - -### High Priority (Test These) - -| Category | Why | Examples | -|----------|-----|----------| -| Core gameplay loop | 90% of player time | Select โ†’ Move โ†’ Attack โ†’ End Turn | -| Turn/phase transitions | State machine boundaries | Phase changes, turn handoff | -| Save โ†’ Load โ†’ Resume | Data integrity | Full round-trip with verification | -| Win/lose conditions | Critical path endpoints | Victory triggers, game over | -| Critical UI flows | First impressions | Menu โ†’ Game โ†’ Pause โ†’ Resume | - -### Medium Priority (Test Key Paths) - -| Category | Why | Examples | -|----------|-----|----------| -| Undo/redo | Easy to break | Action reversal | -| Multiplayer sync | Complex state | Turn handoff in MP | -| Tutorial flow | First-time experience | Guided sequence | - -### Low Priority (Usually Skip for E2E) - -| Category | Why | Better Tested By | -|----------|-----|------------------| -| Edge cases | Combinatorial explosion | Unit tests | -| Visual correctness | Subjective, changes often | Manual testing | -| Performance | Needs dedicated tooling | Performance tests | -| Every permutation | Infinite combinations | Unit + integration | -| AI decision quality | Subjective | Playtesting | - -## E2E Test Organization - -``` -Tests/ -โ”œโ”€โ”€ EditMode/ -โ”‚ โ””โ”€โ”€ ... (existing unit tests) -โ”œโ”€โ”€ PlayMode/ -โ”‚ โ”œโ”€โ”€ Integration/ -โ”‚ โ”‚ โ””โ”€โ”€ ... (existing integration tests) -โ”‚ โ””โ”€โ”€ E2E/ -โ”‚ โ”œโ”€โ”€ E2E.asmdef -โ”‚ โ”œโ”€โ”€ Infrastructure/ -โ”‚ โ”‚ โ”œโ”€โ”€ GameE2ETestFixture.cs -โ”‚ โ”‚ โ”œโ”€โ”€ ScenarioBuilder.cs -โ”‚ โ”‚ โ”œโ”€โ”€ InputSimulator.cs -โ”‚ โ”‚ โ””โ”€โ”€ AsyncAssert.cs -โ”‚ โ”œโ”€โ”€ Scenarios/ -โ”‚ โ”‚ โ”œโ”€โ”€ TurnCycleE2ETests.cs -โ”‚ โ”‚ โ”œโ”€โ”€ MovementE2ETests.cs -โ”‚ โ”‚ โ”œโ”€โ”€ CombatE2ETests.cs -โ”‚ โ”‚ โ”œโ”€โ”€ SaveLoadE2ETests.cs -โ”‚ โ”‚ โ””โ”€โ”€ UIFlowE2ETests.cs -โ”‚ โ””โ”€โ”€ TestData/ -โ”‚ โ”œโ”€โ”€ mid_game_scenario.json -โ”‚ โ”œโ”€โ”€ endgame_scenario.json -โ”‚ โ””โ”€โ”€ edge_case_setup.json -``` - -### Assembly Definition for E2E - -```json -{ - "name": "E2E", - "references": [ - "GameAssembly" - ], - "includePlatforms": [], - "excludePlatforms": [], - "allowUnsafeCode": false, - "overrideReferences": true, - "precompiledReferences": [ - "nunit.framework.dll", - "UnityEngine.TestRunner.dll", - "UnityEditor.TestRunner.dll" - ], - "defineConstraints": [ - "UNITY_INCLUDE_TESTS" - ], - "autoReferenced": false -} -``` - -## CI Considerations - -E2E tests are slower and potentially flaky. Handle with care. - -### Separate CI Job - -```yaml -# GitHub Actions example -e2e-tests: - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: game-ci/unity-test-runner@v4 - with: - testMode: PlayMode - projectPath: . - customParameters: -testCategory E2E -``` - -### Retry Strategy - -```yaml -# Retry flaky tests once before failing -- uses: nick-fields/retry@v2 - with: - timeout_minutes: 15 - max_attempts: 2 - command: | - unity-test-runner --category E2E -``` - -### Failure Artifacts - -Capture screenshots and logs on failure: - -```csharp -[UnityTearDown] -public IEnumerator CaptureOnFailure() -{ - // Yield first to ensure we're on the main thread for screenshot capture - yield return null; - - if (TestContext.CurrentContext.Result.Outcome.Status == TestStatus.Failed) - { - var screenshot = ScreenCapture.CaptureScreenshotAsTexture(); - var bytes = screenshot.EncodeToPNG(); - var screenshotPath = $"TestResults/Screenshots/{TestContext.CurrentContext.Test.Name}.png"; - System.IO.File.WriteAllBytes(screenshotPath, bytes); - - Debug.Log($"[E2E FAILURE] Screenshot saved: {screenshotPath}"); - } -} -``` - -### Execution Frequency - -| Suite | When | Timeout | -|-------|------|---------| -| Unit tests | Every commit | 5 min | -| Integration | Every commit | 10 min | -| E2E (smoke) | Every commit | 15 min | -| E2E (full) | Nightly | 60 min | - -## Avoiding Flaky Tests - -E2E tests are notorious for flakiness. Fight it proactively. - -### DO - -- Use explicit waits with `AsyncAssert.WaitUntil` -- Wait for *game state*, not time -- Clean up thoroughly in TearDown -- Isolate tests completely -- Use deterministic scenarios -- Seed random number generators - -### DON'T - -- Use `yield return new WaitForSeconds(x)` as primary sync -- Depend on test execution order -- Share state between tests -- Rely on animation timing -- Assume frame-perfect timing -- Skip cleanup "because it's slow" - -### Debugging Flaky Tests - -```csharp -// Add verbose logging to track down race conditions -[UnityTest] -public IEnumerator FlakyTest_WithDebugging() -{ - Debug.Log($"[E2E] Test start: {Time.frameCount}"); - - yield return Scenario.Build(); - Debug.Log($"[E2E] Scenario built: {Time.frameCount}"); - - yield return Input.ClickHex(targetHex); - Debug.Log($"[E2E] Input sent: {Time.frameCount}, Selection: {GameState.Selection}"); - - yield return AsyncAssert.WaitUntilVerbose( - () => ExpectedCondition(), - "Expected condition", - timeout: 10f, - logInterval: 0.5f); -} -``` - -## Engine-Specific Notes - -### Unity - -- Use `[UnityTest]` attribute for coroutine-based tests -- Prefer `WaitUntil` over `WaitForSeconds` -- Use `Object.FindFirstObjectByType()` (not the deprecated `FindObjectOfType`) -- Consider `InputTestFixture` for Input System simulation -- Remember: `yield return null` waits one frame - -### Unreal - -- Use `FFunctionalTest` actors for level-based E2E -- `LatentIt` for async test steps in Automation Framework -- Gauntlet for extended E2E suites running in isolated processes -- `ADD_LATENT_AUTOMATION_COMMAND` for sequenced operations - -### Godot - -- Use `await` for async operations in GUT -- `await get_tree().create_timer(x).timeout` for timed waits -- Scene instancing provides natural test isolation -- Use `queue_free()` for cleanup, not `free()` (avoids errors) - -## Anti-Patterns - -### The "Test Everything" Trap - -Don't try to E2E test every edge case. That's what unit tests are for. - -```csharp -// BAD: Testing edge case via E2E -[UnityTest] -public IEnumerator Movement_WithExactlyZeroMP_CannotMove() // Unit test this -{ - // 30 seconds of setup for a condition unit tests cover -} - -// GOOD: E2E tests the journey, unit tests the edge cases -[UnityTest] -public IEnumerator Movement_TypicalPlayerJourney_WorksCorrectly() -{ - // Tests the common path players actually experience -} -``` - -### The "Magic Sleep" Pattern - -```csharp -// BAD: Hoping 2 seconds is enough -yield return new WaitForSeconds(2f); -Assert.IsTrue(condition); - -// GOOD: Wait for the actual condition -yield return AsyncAssert.WaitUntil(() => condition, "description"); -``` - -### The "Shared State" Trap - -```csharp -// BAD: Tests pollute each other -private static int testCounter = 0; // Shared between tests! - -// GOOD: Each test is isolated -[SetUp] -public void Setup() -{ - // Fresh state every test -} -``` - -## Measuring E2E Test Value - -### Coverage Metrics That Matter - -- **Journey coverage**: How many critical player paths are tested? -- **Failure detection rate**: How many real bugs do E2E tests catch? -- **False positive rate**: How often do E2E tests fail spuriously? - -### Warning Signs - -- E2E suite takes > 30 minutes -- Flaky test rate > 5% -- E2E tests duplicate unit test coverage -- Team skips E2E tests because they're "always broken" - -### Health Indicators - -- E2E tests catch integration bugs unit tests miss -- New features include E2E tests for happy path -- Flaky tests are fixed or removed within a sprint -- E2E suite runs on every PR (at least smoke subset) diff --git a/src/modules/bmgd/gametest/knowledge/godot-testing.md b/src/modules/bmgd/gametest/knowledge/godot-testing.md deleted file mode 100644 index ab79e093..00000000 --- a/src/modules/bmgd/gametest/knowledge/godot-testing.md +++ /dev/null @@ -1,875 +0,0 @@ -# Godot GUT Testing Guide - -## Overview - -GUT (Godot Unit Test) is the standard unit testing framework for Godot. It provides a full-featured testing framework with assertions, mocking, and CI integration. - -## Installation - -### Via Asset Library - -1. Open AssetLib in Godot -2. Search for "GUT" -3. Download and install -4. Enable the plugin in Project Settings - -### Via Git Submodule - -```bash -git submodule add https://github.com/bitwes/Gut.git addons/gut -``` - -## Project Structure - -``` -project/ -โ”œโ”€โ”€ addons/ -โ”‚ โ””โ”€โ”€ gut/ -โ”œโ”€โ”€ src/ -โ”‚ โ”œโ”€โ”€ player/ -โ”‚ โ”‚ โ””โ”€โ”€ player.gd -โ”‚ โ””โ”€โ”€ combat/ -โ”‚ โ””โ”€โ”€ damage_calculator.gd -โ””โ”€โ”€ tests/ - โ”œโ”€โ”€ unit/ - โ”‚ โ””โ”€โ”€ test_damage_calculator.gd - โ””โ”€โ”€ integration/ - โ””โ”€โ”€ test_player_combat.gd -``` - -## Basic Test Structure - -### Simple Test Class - -```gdscript -# tests/unit/test_damage_calculator.gd -extends GutTest - -var calculator: DamageCalculator - -func before_each(): - calculator = DamageCalculator.new() - -func after_each(): - calculator.free() - -func test_calculate_base_damage(): - var result = calculator.calculate(100.0, 1.0) - assert_eq(result, 100.0, "Base damage should equal input") - -func test_calculate_critical_hit(): - var result = calculator.calculate(100.0, 2.0) - assert_eq(result, 200.0, "Critical hit should double damage") - -func test_calculate_with_zero_multiplier(): - var result = calculator.calculate(100.0, 0.0) - assert_eq(result, 0.0, "Zero multiplier should result in zero damage") -``` - -### Parameterized Tests - -```gdscript -func test_damage_scenarios(): - var scenarios = [ - {"base": 100.0, "mult": 1.0, "expected": 100.0}, - {"base": 100.0, "mult": 2.0, "expected": 200.0}, - {"base": 50.0, "mult": 1.5, "expected": 75.0}, - {"base": 0.0, "mult": 2.0, "expected": 0.0}, - ] - - for scenario in scenarios: - var result = calculator.calculate(scenario.base, scenario.mult) - assert_eq( - result, - scenario.expected, - "Base %s * %s should equal %s" % [ - scenario.base, scenario.mult, scenario.expected - ] - ) -``` - -## Testing Nodes - -### Scene Testing - -```gdscript -# tests/integration/test_player.gd -extends GutTest - -var player: Player -var player_scene = preload("res://src/player/player.tscn") - -func before_each(): - player = player_scene.instantiate() - add_child(player) - -func after_each(): - player.queue_free() - -func test_player_initial_health(): - assert_eq(player.health, 100, "Player should start with 100 health") - -func test_player_takes_damage(): - player.take_damage(30) - assert_eq(player.health, 70, "Health should be reduced by damage") - -func test_player_dies_at_zero_health(): - player.take_damage(100) - assert_true(player.is_dead, "Player should be dead at 0 health") -``` - -### Testing with Signals - -```gdscript -func test_damage_emits_signal(): - watch_signals(player) - - player.take_damage(10) - - assert_signal_emitted(player, "health_changed") - assert_signal_emit_count(player, "health_changed", 1) - -func test_death_emits_signal(): - watch_signals(player) - - player.take_damage(100) - - assert_signal_emitted(player, "died") -``` - -### Testing with Await - -```gdscript -func test_attack_cooldown(): - player.attack() - assert_true(player.is_attacking) - - # Wait for cooldown - await get_tree().create_timer(player.attack_cooldown).timeout - - assert_false(player.is_attacking) - assert_true(player.can_attack) -``` - -## Mocking and Doubles - -### Creating Doubles - -```gdscript -func test_enemy_uses_pathfinding(): - var mock_pathfinding = double(Pathfinding).new() - stub(mock_pathfinding, "find_path").to_return([Vector2(0, 0), Vector2(10, 10)]) - - var enemy = Enemy.new() - enemy.pathfinding = mock_pathfinding - - enemy.move_to(Vector2(10, 10)) - - assert_called(mock_pathfinding, "find_path") -``` - -### Partial Doubles - -```gdscript -func test_player_inventory(): - var player_double = partial_double(Player).new() - stub(player_double, "save_to_disk").to_do_nothing() - - player_double.add_item("sword") - - assert_eq(player_double.inventory.size(), 1) - assert_called(player_double, "save_to_disk") -``` - -## Physics Testing - -### Testing Collision - -```gdscript -func test_projectile_hits_enemy(): - var projectile = Projectile.new() - var enemy = Enemy.new() - - add_child(projectile) - add_child(enemy) - - projectile.global_position = Vector2(0, 0) - enemy.global_position = Vector2(100, 0) - - projectile.velocity = Vector2(200, 0) - - # Simulate physics frames - for i in range(60): - await get_tree().physics_frame - - assert_true(enemy.was_hit, "Enemy should be hit by projectile") - - projectile.queue_free() - enemy.queue_free() -``` - -### Testing Area2D - -```gdscript -func test_pickup_collected(): - var pickup = Pickup.new() - var player = player_scene.instantiate() - - add_child(pickup) - add_child(player) - - pickup.global_position = Vector2(50, 50) - player.global_position = Vector2(50, 50) - - # Wait for physics to process overlap - await get_tree().physics_frame - await get_tree().physics_frame - - assert_true(pickup.is_queued_for_deletion(), "Pickup should be collected") - - player.queue_free() -``` - -## Input Testing - -### Simulating Input - -```gdscript -func test_jump_on_input(): - var input_event = InputEventKey.new() - input_event.keycode = KEY_SPACE - input_event.pressed = true - - Input.parse_input_event(input_event) - await get_tree().process_frame - - player._unhandled_input(input_event) - - assert_true(player.is_jumping, "Player should jump on space press") -``` - -### Testing Input Actions - -```gdscript -func test_attack_action(): - # Simulate action press - Input.action_press("attack") - await get_tree().process_frame - - player._process(0.016) - - assert_true(player.is_attacking) - - Input.action_release("attack") -``` - -## Resource Testing - -### Testing Custom Resources - -```gdscript -func test_weapon_stats_resource(): - var weapon = WeaponStats.new() - weapon.base_damage = 10.0 - weapon.attack_speed = 2.0 - - assert_eq(weapon.dps, 20.0, "DPS should be damage * speed") - -func test_save_load_resource(): - var original = PlayerData.new() - original.level = 5 - original.gold = 1000 - - ResourceSaver.save(original, "user://test_save.tres") - var loaded = ResourceLoader.load("user://test_save.tres") - - assert_eq(loaded.level, 5) - assert_eq(loaded.gold, 1000) - - DirAccess.remove_absolute("user://test_save.tres") -``` - -## GUT Configuration - -### gut_config.json - -```json -{ - "dirs": ["res://tests/"], - "include_subdirs": true, - "prefix": "test_", - "suffix": ".gd", - "should_exit": true, - "should_exit_on_success": true, - "log_level": 1, - "junit_xml_file": "results.xml", - "font_size": 16 -} -``` - -## CI Integration - -### Command Line Execution - -```bash -# Run all tests -godot --headless -s addons/gut/gut_cmdln.gd - -# Run specific tests -godot --headless -s addons/gut/gut_cmdln.gd \ - -gdir=res://tests/unit \ - -gprefix=test_ - -# With JUnit output -godot --headless -s addons/gut/gut_cmdln.gd \ - -gjunit_xml_file=results.xml -``` - -### GitHub Actions - -```yaml -test: - runs-on: ubuntu-latest - container: - image: barichello/godot-ci:4.2 - steps: - - uses: actions/checkout@v4 - - - name: Run Tests - run: | - godot --headless -s addons/gut/gut_cmdln.gd \ - -gjunit_xml_file=results.xml - - - name: Publish Results - uses: mikepenz/action-junit-report@v4 - with: - report_paths: results.xml -``` - -## Best Practices - -### DO - -- Use `before_each`/`after_each` for setup/teardown -- Free nodes after tests to prevent leaks -- Use meaningful assertion messages -- Group related tests in the same file -- Use `watch_signals` for signal testing -- Await physics frames when testing physics - -### DON'T - -- Don't test Godot's built-in functionality -- Don't rely on execution order between test files -- Don't leave orphan nodes -- Don't use `yield` (use `await` in Godot 4) -- Don't test private methods directly - -## Troubleshooting - -| Issue | Cause | Fix | -| -------------------- | ------------------ | ------------------------------------ | -| Tests not found | Wrong prefix/path | Check gut_config.json | -| Orphan nodes warning | Missing cleanup | Add `queue_free()` in `after_each` | -| Signal not detected | Signal not watched | Call `watch_signals()` before action | -| Physics not working | Missing frames | Await `physics_frame` | -| Flaky tests | Timing issues | Use proper await/signals | - -## C# Testing in Godot - -Godot 4 supports C# via .NET 6+. You can use standard .NET testing frameworks alongside GUT. - -### Project Setup for C# - -``` -project/ -โ”œโ”€โ”€ addons/ -โ”‚ โ””โ”€โ”€ gut/ -โ”œโ”€โ”€ src/ -โ”‚ โ”œโ”€โ”€ Player/ -โ”‚ โ”‚ โ””โ”€โ”€ PlayerController.cs -โ”‚ โ””โ”€โ”€ Combat/ -โ”‚ โ””โ”€โ”€ DamageCalculator.cs -โ”œโ”€โ”€ tests/ -โ”‚ โ”œโ”€โ”€ gdscript/ -โ”‚ โ”‚ โ””โ”€โ”€ test_integration.gd -โ”‚ โ””โ”€โ”€ csharp/ -โ”‚ โ”œโ”€โ”€ Tests.csproj -โ”‚ โ””โ”€โ”€ DamageCalculatorTests.cs -โ””โ”€โ”€ project.csproj -``` - -### C# Test Project Setup - -Create a separate test project that references your game assembly: - -```xml - - - - net6.0 - true - false - - - - - - - - - - - - - -``` - -### Basic C# Unit Tests - -```csharp -// tests/csharp/DamageCalculatorTests.cs -using Xunit; -using YourGame.Combat; - -public class DamageCalculatorTests -{ - private readonly DamageCalculator _calculator; - - public DamageCalculatorTests() - { - _calculator = new DamageCalculator(); - } - - [Fact] - public void Calculate_BaseDamage_ReturnsCorrectValue() - { - var result = _calculator.Calculate(100f, 1f); - Assert.Equal(100f, result); - } - - [Fact] - public void Calculate_CriticalHit_DoublesDamage() - { - var result = _calculator.Calculate(100f, 2f); - Assert.Equal(200f, result); - } - - [Theory] - [InlineData(100f, 0.5f, 50f)] - [InlineData(100f, 1.5f, 150f)] - [InlineData(50f, 2f, 100f)] - public void Calculate_Parameterized_ReturnsExpected( - float baseDamage, float multiplier, float expected) - { - var result = _calculator.Calculate(baseDamage, multiplier); - Assert.Equal(expected, result); - } -} -``` - -### Testing Godot Nodes in C# - -For tests requiring Godot runtime, use a hybrid approach: - -```csharp -// tests/csharp/PlayerControllerTests.cs -using Godot; -using Xunit; -using YourGame.Player; - -public class PlayerControllerTests : IDisposable -{ - private readonly SceneTree _sceneTree; - private PlayerController _player; - - public PlayerControllerTests() - { - // These tests must run within Godot runtime - // Use GodotXUnit or similar adapter - } - - [GodotFact] // Custom attribute for Godot runtime tests - public async Task Player_Move_ChangesPosition() - { - var startPos = _player.GlobalPosition; - - _player.SetInput(new Vector2(1, 0)); - - await ToSignal(GetTree().CreateTimer(0.5f), "timeout"); - - Assert.True(_player.GlobalPosition.X > startPos.X); - } - - public void Dispose() - { - _player?.QueueFree(); - } -} -``` - -### C# Mocking with NSubstitute - -```csharp -using NSubstitute; -using Xunit; - -public class EnemyAITests -{ - [Fact] - public void Enemy_UsesPathfinding_WhenMoving() - { - var mockPathfinding = Substitute.For(); - mockPathfinding.FindPath(Arg.Any(), Arg.Any()) - .Returns(new[] { Vector2.Zero, new Vector2(10, 10) }); - - var enemy = new EnemyAI(mockPathfinding); - - enemy.MoveTo(new Vector2(10, 10)); - - mockPathfinding.Received().FindPath( - Arg.Any(), - Arg.Is(v => v == new Vector2(10, 10))); - } -} -``` - -### Running C# Tests - -```bash -# Run C# unit tests (no Godot runtime needed) -dotnet test tests/csharp/Tests.csproj - -# Run with coverage -dotnet test tests/csharp/Tests.csproj --collect:"XPlat Code Coverage" - -# Run specific test -dotnet test tests/csharp/Tests.csproj --filter "FullyQualifiedName~DamageCalculator" -``` - -### Hybrid Test Strategy - -| Test Type | Framework | When to Use | -| ------------- | ---------------- | ---------------------------------- | -| Pure logic | xUnit/NUnit (C#) | Classes without Godot dependencies | -| Node behavior | GUT (GDScript) | MonoBehaviour-like testing | -| Integration | GUT (GDScript) | Scene and signal testing | -| E2E | GUT (GDScript) | Full gameplay flows | - -## End-to-End Testing - -For comprehensive E2E testing patterns, infrastructure scaffolding, and -scenario builders, see **knowledge/e2e-testing.md**. - -### E2E Infrastructure for Godot - -#### GameE2ETestFixture (GDScript) - -```gdscript -# tests/e2e/infrastructure/game_e2e_test_fixture.gd -extends GutTest -class_name GameE2ETestFixture - -var game_state: GameStateManager -var input_sim: InputSimulator -var scenario: ScenarioBuilder -var _scene_instance: Node - -## Override to specify a different scene for specific test classes. -func get_scene_path() -> String: - return "res://scenes/game.tscn" - -func before_each(): - # Load game scene - var scene = load(get_scene_path()) - _scene_instance = scene.instantiate() - add_child(_scene_instance) - - # Get references - game_state = _scene_instance.get_node("GameStateManager") - assert_not_null(game_state, "GameStateManager not found in scene") - - input_sim = InputSimulator.new() - scenario = ScenarioBuilder.new(game_state) - - # Wait for ready - await wait_for_game_ready() - -func after_each(): - if _scene_instance: - _scene_instance.queue_free() - _scene_instance = null - input_sim = null - scenario = null - -func wait_for_game_ready(timeout: float = 10.0): - var elapsed = 0.0 - while not game_state.is_ready and elapsed < timeout: - await get_tree().process_frame - elapsed += get_process_delta_time() - assert_true(game_state.is_ready, "Game should be ready within timeout") -``` - -#### ScenarioBuilder (GDScript) - -```gdscript -# tests/e2e/infrastructure/scenario_builder.gd -extends RefCounted -class_name ScenarioBuilder - -var _game_state: GameStateManager -var _setup_actions: Array[Callable] = [] - -func _init(game_state: GameStateManager): - _game_state = game_state - -## Load a pre-configured scenario from a save file. -func from_save_file(file_name: String) -> ScenarioBuilder: - _setup_actions.append(func(): await _load_save_file(file_name)) - return self - -## Configure the current turn number. -func on_turn(turn_number: int) -> ScenarioBuilder: - _setup_actions.append(func(): _set_turn(turn_number)) - return self - -## Spawn a unit at position. -func with_unit(faction: int, position: Vector2, movement_points: int = 6) -> ScenarioBuilder: - _setup_actions.append(func(): await _spawn_unit(faction, position, movement_points)) - return self - -## Execute all configured setup actions. -func build() -> void: - for action in _setup_actions: - await action.call() - _setup_actions.clear() - -## Clear pending actions without executing. -func reset() -> void: - _setup_actions.clear() - -# Private implementation -func _load_save_file(file_name: String) -> void: - var path = "res://tests/e2e/test_data/%s" % file_name - await _game_state.load_game(path) - -func _set_turn(turn: int) -> void: - _game_state.set_turn_number(turn) - -func _spawn_unit(faction: int, pos: Vector2, mp: int) -> void: - var unit = _game_state.spawn_unit(faction, pos) - unit.movement_points = mp -``` - -#### InputSimulator (GDScript) - -```gdscript -# tests/e2e/infrastructure/input_simulator.gd -extends RefCounted -class_name InputSimulator - -## Click at a world position. -func click_world_position(world_pos: Vector2) -> void: - var viewport = Engine.get_main_loop().root.get_viewport() - var camera = viewport.get_camera_2d() - var screen_pos = camera.get_screen_center_position() + (world_pos - camera.global_position) - await click_screen_position(screen_pos) - -## Click at a screen position. -func click_screen_position(screen_pos: Vector2) -> void: - var press = InputEventMouseButton.new() - press.button_index = MOUSE_BUTTON_LEFT - press.pressed = true - press.position = screen_pos - - var release = InputEventMouseButton.new() - release.button_index = MOUSE_BUTTON_LEFT - release.pressed = false - release.position = screen_pos - - Input.parse_input_event(press) - await Engine.get_main_loop().process_frame - Input.parse_input_event(release) - await Engine.get_main_loop().process_frame - -## Click a UI button by name. -func click_button(button_name: String) -> void: - var root = Engine.get_main_loop().root - var button = _find_button_recursive(root, button_name) - assert(button != null, "Button '%s' not found in scene tree" % button_name) - - if not button.visible: - push_warning("[InputSimulator] Button '%s' is not visible" % button_name) - if button.disabled: - push_warning("[InputSimulator] Button '%s' is disabled" % button_name) - - button.pressed.emit() - await Engine.get_main_loop().process_frame - -func _find_button_recursive(node: Node, button_name: String) -> Button: - if node is Button and node.name == button_name: - return node - for child in node.get_children(): - var found = _find_button_recursive(child, button_name) - if found: - return found - return null - -## Press and release a key. -func press_key(keycode: Key) -> void: - var press = InputEventKey.new() - press.keycode = keycode - press.pressed = true - - var release = InputEventKey.new() - release.keycode = keycode - release.pressed = false - - Input.parse_input_event(press) - await Engine.get_main_loop().process_frame - Input.parse_input_event(release) - await Engine.get_main_loop().process_frame - -## Simulate an input action. -func action_press(action_name: String) -> void: - Input.action_press(action_name) - await Engine.get_main_loop().process_frame - -func action_release(action_name: String) -> void: - Input.action_release(action_name) - await Engine.get_main_loop().process_frame - -## Reset all input state. -func reset() -> void: - Input.flush_buffered_events() -``` - -#### AsyncAssert (GDScript) - -```gdscript -# tests/e2e/infrastructure/async_assert.gd -extends RefCounted -class_name AsyncAssert - -## Wait until condition is true, or fail after timeout. -static func wait_until( - condition: Callable, - description: String, - timeout: float = 5.0 -) -> void: - var elapsed := 0.0 - while not condition.call() and elapsed < timeout: - await Engine.get_main_loop().process_frame - elapsed += Engine.get_main_loop().root.get_process_delta_time() - - assert(condition.call(), - "Timeout after %.1fs waiting for: %s" % [timeout, description]) - -## Wait for a value to equal expected. -static func wait_for_value( - getter: Callable, - expected: Variant, - description: String, - timeout: float = 5.0 -) -> void: - await wait_until( - func(): return getter.call() == expected, - "%s to equal '%s' (current: '%s')" % [description, expected, getter.call()], - timeout) - -## Wait for a float value within tolerance. -static func wait_for_value_approx( - getter: Callable, - expected: float, - description: String, - tolerance: float = 0.0001, - timeout: float = 5.0 -) -> void: - await wait_until( - func(): return absf(expected - getter.call()) < tolerance, - "%s to equal ~%s ยฑ%s (current: %s)" % [description, expected, tolerance, getter.call()], - timeout) - -## Assert that condition does NOT become true within duration. -static func assert_never_true( - condition: Callable, - description: String, - duration: float = 1.0 -) -> void: - var elapsed := 0.0 - while elapsed < duration: - assert(not condition.call(), - "Condition unexpectedly became true: %s" % description) - await Engine.get_main_loop().process_frame - elapsed += Engine.get_main_loop().root.get_process_delta_time() - -## Wait for specified number of frames. -static func wait_frames(count: int) -> void: - for i in range(count): - await Engine.get_main_loop().process_frame - -## Wait for physics to settle. -static func wait_for_physics(frames: int = 3) -> void: - for i in range(frames): - await Engine.get_main_loop().root.get_tree().physics_frame -``` - -### Example E2E Test (GDScript) - -```gdscript -# tests/e2e/scenarios/test_combat_flow.gd -extends GameE2ETestFixture - -func test_player_can_attack_enemy(): - # GIVEN: Player and enemy in combat range - await scenario \ - .with_unit(Faction.PLAYER, Vector2(100, 100)) \ - .with_unit(Faction.ENEMY, Vector2(150, 100)) \ - .build() - - var enemy = game_state.get_units(Faction.ENEMY)[0] - var initial_health = enemy.health - - # WHEN: Player attacks - await input_sim.click_world_position(Vector2(100, 100)) # Select player - await AsyncAssert.wait_until( - func(): return game_state.selected_unit != null, - "Unit should be selected") - - await input_sim.click_world_position(Vector2(150, 100)) # Attack enemy - - # THEN: Enemy takes damage - await AsyncAssert.wait_until( - func(): return enemy.health < initial_health, - "Enemy should take damage") - -func test_turn_cycle_completes(): - # GIVEN: Game in progress - await scenario.on_turn(1).build() - var starting_turn = game_state.turn_number - - # WHEN: Player ends turn - await input_sim.click_button("EndTurnButton") - await AsyncAssert.wait_until( - func(): return game_state.current_faction == Faction.ENEMY, - "Should switch to enemy turn") - - # AND: Enemy turn completes - await AsyncAssert.wait_until( - func(): return game_state.current_faction == Faction.PLAYER, - "Should return to player turn", - 30.0) # AI might take a while - - # THEN: Turn number incremented - assert_eq(game_state.turn_number, starting_turn + 1) -``` - -### Quick E2E Checklist for Godot - -- [ ] Create `GameE2ETestFixture` base class extending GutTest -- [ ] Implement `ScenarioBuilder` for your game's domain -- [ ] Create `InputSimulator` wrapping Godot Input -- [ ] Add `AsyncAssert` utilities with proper await -- [ ] Organize E2E tests under `tests/e2e/scenarios/` -- [ ] Configure GUT to include E2E test directory -- [ ] Set up CI with headless Godot execution diff --git a/src/modules/bmgd/gametest/knowledge/input-testing.md b/src/modules/bmgd/gametest/knowledge/input-testing.md deleted file mode 100644 index ed4f7b37..00000000 --- a/src/modules/bmgd/gametest/knowledge/input-testing.md +++ /dev/null @@ -1,315 +0,0 @@ -# Input Testing Guide - -## Overview - -Input testing validates that all supported input devices work correctly across platforms. Poor input handling frustrates players instantlyโ€”responsive, accurate input is foundational to game feel. - -## Input Categories - -### Device Types - -| Device | Platforms | Key Concerns | -| ----------------- | -------------- | ----------------------------------- | -| Keyboard + Mouse | PC | Key conflicts, DPI sensitivity | -| Gamepad (Xbox/PS) | PC, Console | Deadzone, vibration, button prompts | -| Touch | Mobile, Switch | Multi-touch, gesture recognition | -| Motion Controls | Switch, VR | Calibration, drift, fatigue | -| Specialty | Various | Flight sticks, wheels, fight sticks | - -### Input Characteristics - -| Characteristic | Description | Test Focus | -| -------------- | ---------------------------- | -------------------------------- | -| Responsiveness | Input-to-action delay | Should feel instant (< 100ms) | -| Accuracy | Input maps to correct action | No ghost inputs or missed inputs | -| Consistency | Same input = same result | Deterministic behavior | -| Accessibility | Alternative input support | Remapping, assist options | - -## Test Scenarios - -### Keyboard and Mouse - -``` -SCENARIO: All Keybinds Functional - GIVEN default keyboard bindings - WHEN each bound key is pressed - THEN corresponding action triggers - AND no key conflicts exist - -SCENARIO: Key Remapping - GIVEN player remaps "Jump" from Space to F - WHEN F is pressed - THEN jump action triggers - AND Space no longer triggers jump - AND remapping persists after restart - -SCENARIO: Mouse Sensitivity - GIVEN sensitivity set to 5 (mid-range) - WHEN mouse moves 10cm - THEN camera rotation matches expected degrees - AND movement feels consistent at different frame rates - -SCENARIO: Mouse Button Support - GIVEN mouse with 5+ buttons - WHEN side buttons are pressed - THEN they can be bound to actions - AND they function correctly in gameplay -``` - -### Gamepad - -``` -SCENARIO: Analog Stick Deadzone - GIVEN controller with slight stick drift - WHEN stick is in neutral position - THEN no movement occurs (deadzone filters drift) - AND intentional small movements still register - -SCENARIO: Trigger Pressure - GIVEN analog triggers - WHEN trigger is partially pressed - THEN partial values are read (e.g., 0.5 for half-press) - AND full press reaches 1.0 - -SCENARIO: Controller Hot-Swap - GIVEN game running with keyboard - WHEN gamepad is connected - THEN input prompts switch to gamepad icons - AND gamepad input works immediately - AND keyboard still works if used - -SCENARIO: Vibration Feedback - GIVEN rumble-enabled controller - WHEN damage is taken - THEN controller vibrates appropriately - AND vibration intensity matches damage severity -``` - -### Touch Input - -``` -SCENARIO: Multi-Touch Accuracy - GIVEN virtual joystick and buttons - WHEN left thumb on joystick AND right thumb on button - THEN both inputs register simultaneously - AND no interference between touch points - -SCENARIO: Gesture Recognition - GIVEN swipe-to-attack mechanic - WHEN player swipes right - THEN attack direction matches swipe - AND swipe is distinguished from tap - -SCENARIO: Touch Target Size - GIVEN minimum touch target of 44x44 points - WHEN buttons are placed - THEN all interactive elements meet minimum size - AND elements have adequate spacing -``` - -## Platform-Specific Testing - -### PC - -- Multiple keyboard layouts (QWERTY, AZERTY, QWERTZ) -- Different mouse DPI settings (400-3200+) -- Multiple monitors (cursor confinement) -- Background application conflicts -- Steam Input API integration - -### Console - -| Platform | Specific Tests | -| ----------- | ------------------------------------------ | -| PlayStation | Touchpad, adaptive triggers, haptics | -| Xbox | Impulse triggers, Elite controller paddles | -| Switch | Joy-Con detachment, gyro, HD rumble | - -### Mobile - -- Different screen sizes and aspect ratios -- Notch/cutout avoidance -- External controller support -- Apple MFi / Android gamepad compatibility - -## Automated Test Examples - -### Unity - -```csharp -using UnityEngine.InputSystem; - -[UnityTest] -public IEnumerator Movement_WithGamepad_RespondsToStick() -{ - var gamepad = InputSystem.AddDevice(); - - yield return null; - - // Simulate stick input - Set(gamepad.leftStick, new Vector2(1, 0)); - yield return new WaitForSeconds(0.1f); - - Assert.Greater(player.transform.position.x, 0f, - "Player should move right"); - - InputSystem.RemoveDevice(gamepad); -} - -[UnityTest] -public IEnumerator InputLatency_UnderLoad_StaysAcceptable() -{ - float inputTime = Time.realtimeSinceStartup; - bool actionTriggered = false; - - player.OnJump += () => { - float latency = (Time.realtimeSinceStartup - inputTime) * 1000; - Assert.Less(latency, 100f, "Input latency should be under 100ms"); - actionTriggered = true; - }; - - var keyboard = InputSystem.AddDevice(); - Press(keyboard.spaceKey); - - yield return new WaitForSeconds(0.2f); - - Assert.IsTrue(actionTriggered, "Jump should have triggered"); -} - -[Test] -public void Deadzone_FiltersSmallInputs() -{ - var settings = new InputSettings { stickDeadzone = 0.2f }; - - // Input below deadzone - var filtered = InputProcessor.ApplyDeadzone(new Vector2(0.1f, 0.1f), settings); - Assert.AreEqual(Vector2.zero, filtered); - - // Input above deadzone - filtered = InputProcessor.ApplyDeadzone(new Vector2(0.5f, 0.5f), settings); - Assert.AreNotEqual(Vector2.zero, filtered); -} -``` - -### Unreal - -```cpp -bool FInputTest::RunTest(const FString& Parameters) -{ - // Test gamepad input mapping - APlayerController* PC = GetWorld()->GetFirstPlayerController(); - - // Simulate gamepad stick input - FInputKeyParams Params; - Params.Key = EKeys::Gamepad_LeftX; - Params.Delta = FVector(1.0f, 0, 0); - PC->InputKey(Params); - - // Verify movement - APawn* Pawn = PC->GetPawn(); - FVector Velocity = Pawn->GetVelocity(); - - TestTrue("Pawn should be moving", Velocity.SizeSquared() > 0); - - return true; -} -``` - -### Godot - -```gdscript -func test_input_action_mapping(): - # Verify action exists - assert_true(InputMap.has_action("jump")) - - # Simulate input - var event = InputEventKey.new() - event.keycode = KEY_SPACE - event.pressed = true - - Input.parse_input_event(event) - await get_tree().process_frame - - assert_true(Input.is_action_just_pressed("jump")) - -func test_gamepad_deadzone(): - var input = Vector2(0.15, 0.1) - var deadzone = 0.2 - - var processed = input_processor.apply_deadzone(input, deadzone) - - assert_eq(processed, Vector2.ZERO, "Small input should be filtered") - -func test_controller_hotswap(): - # Simulate controller connect - Input.joy_connection_changed(0, true) - await get_tree().process_frame - - var prompt_icon = ui.get_action_prompt("jump") - - assert_true(prompt_icon.texture.resource_path.contains("gamepad"), - "Should show gamepad prompts after controller connect") -``` - -## Accessibility Testing - -### Requirements Checklist - -- [ ] Full keyboard navigation (no mouse required) -- [ ] Remappable controls for all actions -- [ ] Button hold alternatives to rapid press -- [ ] Toggle options for hold actions -- [ ] One-handed control schemes -- [ ] Colorblind-friendly UI indicators -- [ ] Screen reader support for menus - -### Accessibility Test Scenarios - -``` -SCENARIO: Keyboard-Only Navigation - GIVEN mouse is disconnected - WHEN navigating through all menus - THEN all menu items are reachable via keyboard - AND focus indicators are clearly visible - -SCENARIO: Button Hold Toggle - GIVEN "sprint requires hold" is toggled OFF - WHEN sprint button is tapped once - THEN sprint activates - AND sprint stays active until tapped again - -SCENARIO: Reduced Button Mashing - GIVEN QTE assist mode enabled - WHEN QTE sequence appears - THEN single press advances sequence - AND no rapid input required -``` - -## Performance Metrics - -| Metric | Target | Maximum Acceptable | -| ----------------------- | --------------- | ------------------ | -| Input-to-render latency | < 50ms | 100ms | -| Polling rate match | 1:1 with device | No input loss | -| Deadzone processing | < 1ms | 5ms | -| Rebind save/load | < 100ms | 500ms | - -## Best Practices - -### DO - -- Test with actual hardware, not just simulated input -- Support simultaneous keyboard + gamepad -- Provide sensible default deadzones -- Show device-appropriate button prompts -- Allow complete control remapping -- Test at different frame rates - -### DON'T - -- Assume controller layout (Xbox vs PlayStation) -- Hard-code input mappings -- Ignore analog input precision -- Skip accessibility considerations -- Forget about input during loading/cutscenes -- Neglect testing with worn/drifting controllers diff --git a/src/modules/bmgd/gametest/knowledge/localization-testing.md b/src/modules/bmgd/gametest/knowledge/localization-testing.md deleted file mode 100644 index fd4b0344..00000000 --- a/src/modules/bmgd/gametest/knowledge/localization-testing.md +++ /dev/null @@ -1,304 +0,0 @@ -# Localization Testing Guide - -## Overview - -Localization testing ensures games work correctly across languages, regions, and cultures. Beyond translation, it validates text display, cultural appropriateness, and regional compliance. - -## Test Categories - -### Linguistic Testing - -| Category | Focus | Examples | -| -------------------- | ----------------------- | ------------------------------ | -| Translation accuracy | Meaning preserved | Idioms, game terminology | -| Grammar/spelling | Language correctness | Verb tense, punctuation | -| Consistency | Same terms throughout | "Health" vs "HP" vs "Life" | -| Context | Meaning in game context | Item names, skill descriptions | - -### Functional Testing - -| Category | Focus | Examples | -| -------------- | ----------------------- | --------------------------- | -| Text display | Fits in UI | Button labels, dialog boxes | -| Font support | Characters render | CJK, Cyrillic, Arabic | -| Text expansion | Longer translations | German is ~30% longer | -| RTL support | Right-to-left languages | Arabic, Hebrew layouts | - -### Cultural Testing - -| Category | Focus | Examples | -| -------------------- | ------------------ | ------------------------- | -| Cultural sensitivity | Offensive content | Gestures, symbols, colors | -| Regional compliance | Legal requirements | Ratings, gambling laws | -| Date/time formats | Local conventions | DD/MM/YYYY vs MM/DD/YYYY | -| Number formats | Decimal separators | 1,000.00 vs 1.000,00 | - -## Test Scenarios - -### Text Display - -``` -SCENARIO: Text Fits UI Elements - GIVEN all localized strings - WHEN displayed in target language - THEN text fits within UI boundaries - AND no truncation or overflow occurs - AND text remains readable - -SCENARIO: Dynamic Text Insertion - GIVEN template "Player {name} scored {points} points" - WHEN name="Alexander" and points=1000 - THEN German: "Spieler Alexander hat 1.000 Punkte erzielt" - AND text fits UI element - AND variables are correctly formatted for locale - -SCENARIO: Plural Forms - GIVEN English "1 coin" / "5 coins" - WHEN displaying in Polish (4 plural forms) - THEN correct plural form is used - AND all plural forms are translated -``` - -### Character Support - -``` -SCENARIO: CJK Character Rendering - GIVEN Japanese localization - WHEN displaying text with kanji/hiragana/katakana - THEN all characters render correctly - AND no missing glyphs (tofu boxes) - AND line breaks respect CJK rules - -SCENARIO: Special Characters - GIVEN text with accented characters (รฉ, รฑ, รผ) - WHEN displayed in-game - THEN all characters render correctly - AND sorting works correctly - -SCENARIO: User-Generated Content - GIVEN player can name character - WHEN name includes non-Latin characters - THEN name displays correctly - AND name saves/loads correctly - AND name appears correctly to other players -``` - -### Layout and Direction - -``` -SCENARIO: Right-to-Left Layout - GIVEN Arabic localization - WHEN viewing UI - THEN text reads right-to-left - AND UI elements mirror appropriately - AND numbers remain left-to-right - AND mixed content (Arabic + English) displays correctly - -SCENARIO: Text Expansion Accommodation - GIVEN English UI "OK" / "Cancel" buttons - WHEN localized to German "OK" / "Abbrechen" - THEN button expands or text size adjusts - AND button remains clickable - AND layout doesn't break -``` - -## Locale-Specific Formatting - -### Date and Time - -| Locale | Date Format | Time Format | -| ------ | -------------- | ----------- | -| en-US | 12/25/2024 | 3:30 PM | -| en-GB | 25/12/2024 | 15:30 | -| de-DE | 25.12.2024 | 15:30 Uhr | -| ja-JP | 2024ๅนด12ๆœˆ25ๆ—ฅ | 15ๆ™‚30ๅˆ† | - -### Numbers and Currency - -| Locale | Number | Currency | -| ------ | -------- | ---------- | -| en-US | 1,234.56 | $1,234.56 | -| de-DE | 1.234,56 | 1.234,56 โ‚ฌ | -| fr-FR | 1 234,56 | 1 234,56 โ‚ฌ | -| ja-JP | 1,234.56 | ยฅ1,235 | - -## Automated Test Examples - -### Unity - -```csharp -using UnityEngine.Localization; - -[Test] -public void Localization_AllKeysHaveTranslations([Values("en", "de", "ja", "zh-CN")] string locale) -{ - var stringTable = LocalizationSettings.StringDatabase - .GetTable("GameStrings", new Locale(locale)); - - foreach (var entry in stringTable) - { - Assert.IsFalse(string.IsNullOrEmpty(entry.Value.LocalizedValue), - $"Missing translation for '{entry.Key}' in {locale}"); - } -} - -[Test] -public void TextFits_AllUIElements() -{ - var languages = new[] { "en", "de", "fr", "ja" }; - - foreach (var lang in languages) - { - LocalizationSettings.SelectedLocale = new Locale(lang); - - foreach (var textElement in FindObjectsOfType()) - { - var rectTransform = textElement.GetComponent(); - var textComponent = textElement.GetComponent(); - - Assert.LessOrEqual( - textComponent.preferredWidth, - rectTransform.rect.width, - $"Text overflows in {lang}: {textElement.name}"); - } - } -} - -[TestCase("en", 1, "1 coin")] -[TestCase("en", 5, "5 coins")] -[TestCase("ru", 1, "1 ะผะพะฝะตั‚ะฐ")] -[TestCase("ru", 2, "2 ะผะพะฝะตั‚ั‹")] -[TestCase("ru", 5, "5 ะผะพะฝะตั‚")] -public void Pluralization_ReturnsCorrectForm(string locale, int count, string expected) -{ - var result = Localization.GetPlural("coin", count, locale); - Assert.AreEqual(expected, result); -} -``` - -### Unreal - -```cpp -bool FLocalizationTest::RunTest(const FString& Parameters) -{ - TArray Cultures = {"en", "de", "ja", "ko"}; - - for (const FString& Culture : Cultures) - { - FInternationalization::Get().SetCurrentCulture(Culture); - - // Test critical strings exist - FText LocalizedText = NSLOCTEXT("Game", "StartButton", "Start"); - TestFalse( - FString::Printf(TEXT("Missing StartButton in %s"), *Culture), - LocalizedText.IsEmpty()); - - // Test number formatting - FText NumberText = FText::AsNumber(1234567); - TestTrue( - TEXT("Number should be formatted"), - NumberText.ToString().Len() > 7); // Has separators - } - - return true; -} -``` - -### Godot - -```gdscript -func test_all_translations_complete(): - var locales = ["en", "de", "ja", "es"] - var keys = TranslationServer.get_all_keys() - - for locale in locales: - TranslationServer.set_locale(locale) - for key in keys: - var translated = tr(key) - assert_ne(translated, key, - "Missing translation for '%s' in %s" % [key, locale]) - -func test_plural_forms(): - TranslationServer.set_locale("ru") - - assert_eq(tr_n("coin", "coins", 1), "1 ะผะพะฝะตั‚ะฐ") - assert_eq(tr_n("coin", "coins", 2), "2 ะผะพะฝะตั‚ั‹") - assert_eq(tr_n("coin", "coins", 5), "5 ะผะพะฝะตั‚") - assert_eq(tr_n("coin", "coins", 21), "21 ะผะพะฝะตั‚ะฐ") - -func test_text_fits_buttons(): - var locales = ["en", "de", "fr"] - - for locale in locales: - TranslationServer.set_locale(locale) - await get_tree().process_frame # Allow UI update - - for button in get_tree().get_nodes_in_group("localized_buttons"): - var label = button.get_node("Label") - assert_lt(label.size.x, button.size.x, - "Button text overflows in %s: %s" % [locale, button.name]) -``` - -## Visual Verification Checklist - -### Text Display - -- [ ] No truncation in any language -- [ ] Consistent font sizing -- [ ] Proper line breaks -- [ ] No overlapping text - -### UI Layout - -- [ ] Buttons accommodate longer text -- [ ] Dialog boxes resize appropriately -- [ ] Menu items align correctly -- [ ] Scrollbars appear when needed - -### Cultural Elements - -- [ ] Icons are culturally appropriate -- [ ] Colors don't have negative connotations -- [ ] Gestures are region-appropriate -- [ ] No unintended political references - -## Regional Compliance - -### Ratings Requirements - -| Region | Rating Board | Special Requirements | -| ------------- | ------------ | ------------------------- | -| North America | ESRB | Content descriptors | -| Europe | PEGI | Age-appropriate icons | -| Japan | CERO | Strict content guidelines | -| Germany | USK | Violence restrictions | -| China | GRAC | Approval process | - -### Common Regional Issues - -| Issue | Regions Affected | Solution | -| ---------------- | ---------------- | ------------------------ | -| Blood color | Japan, Germany | Option for green/disable | -| Gambling imagery | Many regions | Remove or modify | -| Skulls/bones | China | Alternative designs | -| Nazi imagery | Germany | Remove entirely | - -## Best Practices - -### DO - -- Test with native speakers -- Plan for text expansion (reserve 30% extra space) -- Use placeholder text during development (Lorem ipsum-style) -- Support multiple input methods (IME for CJK) -- Test all language combinations (UI language + audio language) -- Validate string format parameters - -### DON'T - -- Hard-code strings in source code -- Assume left-to-right layout -- Concatenate translated strings -- Use machine translation without review -- Forget about date/time/number formatting -- Ignore cultural context of images and icons diff --git a/src/modules/bmgd/gametest/knowledge/multiplayer-testing.md b/src/modules/bmgd/gametest/knowledge/multiplayer-testing.md deleted file mode 100644 index 7ee8ddf1..00000000 --- a/src/modules/bmgd/gametest/knowledge/multiplayer-testing.md +++ /dev/null @@ -1,322 +0,0 @@ -# Multiplayer Testing Guide - -## Overview - -Multiplayer testing validates network code, synchronization, and the player experience under real-world conditions. Network bugs are notoriously hard to reproduceโ€”systematic testing is essential. - -## Test Categories - -### Synchronization Testing - -| Test Type | Description | Priority | -| ------------------- | ---------------------------------------- | -------- | -| State sync | All clients see consistent game state | P0 | -| Position sync | Character positions match across clients | P0 | -| Event ordering | Actions occur in correct sequence | P0 | -| Conflict resolution | Simultaneous actions handled correctly | P1 | -| Late join | New players sync correctly mid-game | P1 | - -### Network Conditions - -| Condition | Simulation Method | Test Focus | -| --------------- | ----------------- | ------------------------ | -| High latency | 200-500ms delay | Input responsiveness | -| Packet loss | 5-20% drop rate | State recovery | -| Jitter | Variable delay | Interpolation smoothness | -| Bandwidth limit | Throttle to 1Mbps | Data prioritization | -| Disconnection | Kill connection | Reconnection handling | - -## Test Scenarios - -### Basic Multiplayer - -``` -SCENARIO: Player Join/Leave - GIVEN host has started multiplayer session - WHEN Player 2 joins - THEN Player 2 appears in host's game - AND Player 1 appears in Player 2's game - AND player counts sync across all clients - -SCENARIO: State Synchronization - GIVEN 4 players in match - WHEN Player 1 picks up item at position (10, 5) - THEN item disappears for all players - AND Player 1's inventory updates for all players - AND no duplicate pickups possible - -SCENARIO: Combat Synchronization - GIVEN Player 1 attacks Player 2 - WHEN attack hits - THEN damage is consistent on all clients - AND hit effects play for all players - AND health updates sync within 100ms -``` - -### Network Degradation - -``` -SCENARIO: High Latency Gameplay - GIVEN 200ms latency between players - WHEN Player 1 moves forward - THEN movement is smooth on Player 1's screen - AND other players see interpolated movement - AND position converges within 500ms - -SCENARIO: Packet Loss Recovery - GIVEN 10% packet loss - WHEN important game event occurs (goal, kill, etc.) - THEN event is eventually delivered - AND game state remains consistent - AND no duplicate events processed - -SCENARIO: Player Disconnection - GIVEN Player 2 disconnects unexpectedly - WHEN 5 seconds pass - THEN other players are notified - AND Player 2's character handles gracefully (despawn/AI takeover) - AND game continues without crash -``` - -### Edge Cases - -``` -SCENARIO: Simultaneous Actions - GIVEN Player 1 and Player 2 grab same item simultaneously - WHEN both inputs arrive at server - THEN only one player receives item - AND other player sees consistent state - AND no item duplication - -SCENARIO: Host Migration - GIVEN host disconnects - WHEN migration begins - THEN new host is selected - AND game state transfers correctly - AND gameplay resumes within 10 seconds - -SCENARIO: Reconnection - GIVEN Player 2 disconnects temporarily - WHEN Player 2 reconnects within 60 seconds - THEN Player 2 rejoins same session - AND state is synchronized - AND progress is preserved -``` - -## Network Simulation Tools - -### Unity - -```csharp -// Using Unity Transport with Network Simulator -using Unity.Netcode; - -public class NetworkSimulator : MonoBehaviour -{ - [SerializeField] private int latencyMs = 100; - [SerializeField] private float packetLossPercent = 5f; - [SerializeField] private int jitterMs = 20; - - void Start() - { - var transport = NetworkManager.Singleton.GetComponent(); - var simulator = transport.GetSimulatorParameters(); - - simulator.PacketDelayMS = latencyMs; - simulator.PacketDropRate = (int)(packetLossPercent * 100); - simulator.PacketJitterMS = jitterMs; - } -} - -// Test -[UnityTest] -public IEnumerator Position_UnderLatency_ConvergesWithinThreshold() -{ - EnableNetworkSimulation(latencyMs: 200); - - // Move player - player1.Move(Vector3.forward * 10); - - yield return new WaitForSeconds(1f); - - // Check other client's view - var player1OnClient2 = client2.GetPlayerPosition(player1.Id); - var actualPosition = player1.transform.position; - - Assert.Less(Vector3.Distance(player1OnClient2, actualPosition), 0.5f); -} -``` - -### Unreal - -```cpp -// Using Network Emulation -void UNetworkTestHelper::EnableLatencySimulation(int32 LatencyMs) -{ - if (UNetDriver* NetDriver = GetWorld()->GetNetDriver()) - { - FPacketSimulationSettings Settings; - Settings.PktLag = LatencyMs; - Settings.PktLagVariance = LatencyMs / 10; - Settings.PktLoss = 0; - - NetDriver->SetPacketSimulationSettings(Settings); - } -} - -// Functional test for sync -void AMultiplayerSyncTest::StartTest() -{ - Super::StartTest(); - - // Spawn item on server - APickupItem* Item = GetWorld()->SpawnActor( - ItemClass, FVector(0, 0, 100)); - - // Wait for replication - FTimerHandle TimerHandle; - GetWorld()->GetTimerManager().SetTimer(TimerHandle, [this, Item]() - { - // Verify client has item - if (VerifyItemExistsOnAllClients(Item)) - { - FinishTest(EFunctionalTestResult::Succeeded, "Item replicated"); - } - else - { - FinishTest(EFunctionalTestResult::Failed, "Item not found on clients"); - } - }, 2.0f, false); -} -``` - -### Godot - -```gdscript -# Network simulation -extends Node - -var simulated_latency_ms := 0 -var packet_loss_percent := 0.0 - -func _ready(): - # Hook into network to simulate conditions - multiplayer.peer_packet_received.connect(_on_packet_received) - -func _on_packet_received(id: int, packet: PackedByteArray): - if packet_loss_percent > 0 and randf() < packet_loss_percent / 100: - return # Drop packet - - if simulated_latency_ms > 0: - await get_tree().create_timer(simulated_latency_ms / 1000.0).timeout - - _process_packet(id, packet) - -# Test -func test_position_sync_under_latency(): - NetworkSimulator.simulated_latency_ms = 200 - - # Move player on host - host_player.position = Vector3(100, 0, 100) - - await get_tree().create_timer(1.0).timeout - - # Check client view - var client_view_position = client.get_remote_player_position(host_player.id) - var distance = host_player.position.distance_to(client_view_position) - - assert_lt(distance, 1.0, "Position should converge within 1 unit") -``` - -## Dedicated Server Testing - -### Test Matrix - -| Scenario | Test Focus | -| --------------------- | ------------------------------------ | -| Server startup | Clean initialization, port binding | -| Client authentication | Login validation, session management | -| Server tick rate | Consistent updates under load | -| Maximum players | Performance at player cap | -| Server crash recovery | State preservation, reconnection | - -### Load Testing - -``` -SCENARIO: Maximum Players - GIVEN server configured for 64 players - WHEN 64 players connect - THEN all connections succeed - AND server tick rate stays above 60Hz - AND latency stays below 50ms - -SCENARIO: Stress Test - GIVEN 64 players performing actions simultaneously - WHEN running for 10 minutes - THEN no memory leaks - AND no desync events - AND server CPU below 80% -``` - -## Matchmaking Testing - -``` -SCENARIO: Skill-Based Matching - GIVEN players with skill ratings [1000, 1050, 2000, 2100] - WHEN matchmaking runs - THEN [1000, 1050] are grouped together - AND [2000, 2100] are grouped together - -SCENARIO: Region Matching - GIVEN players from US-East, US-West, EU - WHEN matchmaking runs - THEN players prefer same-region matches - AND cross-region only when necessary - AND latency is acceptable for all players - -SCENARIO: Queue Timeout - GIVEN player waiting in queue - WHEN 3 minutes pass without match - THEN matchmaking expands search criteria - AND player is notified of expanded search -``` - -## Security Testing - -| Vulnerability | Test Method | -| ---------------- | --------------------------- | -| Speed hacking | Validate movement on server | -| Teleportation | Check position delta limits | -| Damage hacking | Server-authoritative damage | -| Packet injection | Validate packet checksums | -| Replay attacks | Use unique session tokens | - -## Performance Metrics - -| Metric | Good | Acceptable | Poor | -| --------------------- | --------- | ---------- | ---------- | -| Round-trip latency | < 50ms | < 100ms | > 150ms | -| Sync delta | < 100ms | < 200ms | > 500ms | -| Packet loss tolerance | < 5% | < 10% | > 15% | -| Bandwidth per player | < 10 KB/s | < 50 KB/s | > 100 KB/s | -| Server tick rate | 60+ Hz | 30+ Hz | < 20 Hz | - -## Best Practices - -### DO - -- Test with real network conditions, not just localhost -- Simulate worst-case scenarios (high latency + packet loss) -- Use server-authoritative design for competitive games -- Implement lag compensation for fast-paced games -- Test host migration paths -- Log network events for debugging - -### DON'T - -- Trust client data for important game state -- Assume stable connections -- Skip testing with maximum player counts -- Ignore edge cases (simultaneous actions) -- Test only in ideal network conditions -- Forget to test reconnection flows diff --git a/src/modules/bmgd/gametest/knowledge/performance-testing.md b/src/modules/bmgd/gametest/knowledge/performance-testing.md deleted file mode 100644 index 38f363e5..00000000 --- a/src/modules/bmgd/gametest/knowledge/performance-testing.md +++ /dev/null @@ -1,204 +0,0 @@ -# Performance Testing for Games - -## Overview - -Performance testing ensures your game runs smoothly on target hardware. Frame rate, load times, and memory usage directly impact player experience. - -## Key Performance Metrics - -### Frame Rate - -- **Target:** 30fps, 60fps, 120fps depending on platform/genre -- **Measure:** Average, minimum, 1% low, 0.1% low -- **Goal:** Consistent frame times, no stutters - -### Frame Time Budget - -At 60fps, you have 16.67ms per frame: - -``` -Rendering: 8ms (48%) -Game Logic: 4ms (24%) -Physics: 2ms (12%) -Audio: 1ms (6%) -UI: 1ms (6%) -Headroom: 0.67ms (4%) -``` - -### Memory - -- **RAM:** Total allocation, peak usage, fragmentation -- **VRAM:** Texture memory, render targets, buffers -- **Goal:** Stay within platform limits with headroom - -### Load Times - -- **Initial Load:** Time to main menu -- **Level Load:** Time between scenes -- **Streaming:** Asset loading during gameplay -- **Goal:** Meet platform certification requirements - -## Profiling Tools by Engine - -### Unity - -- **Profiler Window** - CPU, GPU, memory, rendering -- **Frame Debugger** - Draw call analysis -- **Memory Profiler** - Heap snapshots -- **Profile Analyzer** - Compare captures - -### Unreal Engine - -- **Unreal Insights** - Comprehensive profiling -- **Stat Commands** - Runtime statistics -- **GPU Visualizer** - GPU timing breakdown -- **Memory Report** - Allocation tracking - -### Godot - -- **Debugger** - Built-in profiler -- **Monitors** - Real-time metrics -- **Remote Debugger** - Profile on device - -### Platform Tools - -- **PIX** (Xbox/Windows) - GPU debugging -- **RenderDoc** - GPU capture and replay -- **Instruments** (iOS/macOS) - Apple profiling -- **Android Profiler** - Android Studio tools - -## Performance Testing Process - -### 1. Establish Baselines - -- Profile on target hardware -- Record key metrics -- Create benchmark scenes - -### 2. Set Budgets - -- Define frame time budgets per system -- Set memory limits -- Establish load time targets - -### 3. Monitor Continuously - -- Integrate profiling in CI -- Track metrics over time -- Alert on regressions - -### 4. Optimize When Needed - -- Profile before optimizing -- Target biggest bottlenecks -- Verify improvements - -## Common Performance Issues - -### CPU Bottlenecks - -| Issue | Symptoms | Solution | -| --------------------- | ----------------- | --------------------------------- | -| Too many game objects | Slow update loop | Object pooling, LOD | -| Expensive AI | Spiky frame times | Budget AI, spread over frames | -| Physics overload | Physics spikes | Simplify colliders, reduce bodies | -| GC stutter | Regular hitches | Avoid runtime allocations | - -### GPU Bottlenecks - -| Issue | Symptoms | Solution | -| ------------------- | ----------------- | -------------------------------- | -| Overdraw | Fill rate limited | Occlusion culling, reduce layers | -| Too many draw calls | CPU-GPU bound | Batching, instancing, atlasing | -| Shader complexity | Long GPU times | Simplify shaders, LOD | -| Resolution too high | Fill rate limited | Dynamic resolution, FSR/DLSS | - -### Memory Issues - -| Issue | Symptoms | Solution | -| ------------- | ----------------- | ---------------------------- | -| Texture bloat | High VRAM | Compress, mipmap, stream | -| Leaks | Growing memory | Track allocations, fix leaks | -| Fragmentation | OOM despite space | Pool allocations, defrag | - -## Benchmark Scenes - -Create standardized test scenarios: - -### Stress Test Scene - -- Maximum entities on screen -- Complex visual effects -- Worst-case for performance - -### Typical Gameplay Scene - -- Representative of normal play -- Average entity count -- Baseline for comparison - -### Isolated System Tests - -- Combat only (no rendering) -- Rendering only (no game logic) -- AI only (pathfinding stress) - -## Automated Performance Testing - -### CI Integration - -```yaml -# Example: Fail build if frame time exceeds budget -performance_test: - script: - - run_benchmark --scene stress_test - - check_metrics --max-frame-time 16.67ms --max-memory 2GB - artifacts: - - performance_report.json -``` - -### Regression Detection - -- Compare against previous builds -- Alert on significant changes (>10%) -- Track trends over time - -## Platform-Specific Considerations - -### Console - -- Fixed hardware targets -- Strict certification requirements -- Thermal throttling concerns - -### PC - -- Wide hardware range -- Scalable quality settings -- Min/recommended specs - -### Mobile - -- Thermal throttling -- Battery impact -- Memory constraints -- Background app pressure - -## Performance Testing Checklist - -### Before Release - -- [ ] Profiled on all target platforms -- [ ] Frame rate targets met -- [ ] No memory leaks -- [ ] Load times acceptable -- [ ] No GC stutters in gameplay -- [ ] Thermal tests passed (mobile/console) -- [ ] Certification requirements met - -### Ongoing - -- [ ] Performance tracked in CI -- [ ] Regression alerts configured -- [ ] Benchmark scenes maintained -- [ ] Budgets documented and enforced diff --git a/src/modules/bmgd/gametest/knowledge/playtesting.md b/src/modules/bmgd/gametest/knowledge/playtesting.md deleted file mode 100644 index c22242a9..00000000 --- a/src/modules/bmgd/gametest/knowledge/playtesting.md +++ /dev/null @@ -1,384 +0,0 @@ -# Playtesting Fundamentals - -## Overview - -Playtesting is the process of having people play your game to gather feedback and identify issues. It's distinct from QA testing in that it focuses on player experience, fun factor, and design validation rather than bug hunting. - -## Types of Playtesting - -### Internal Playtesting - -- **Developer Testing** - Daily testing during development -- **Team Testing** - Cross-discipline team plays together -- **Best for:** Rapid iteration, catching obvious issues - -### External Playtesting - -- **Friends & Family** - Trusted external testers -- **Focus Groups** - Targeted demographic testing -- **Public Beta** - Large-scale community testing -- **Best for:** Fresh perspectives, UX validation - -### Specialized Playtesting - -- **Accessibility Testing** - Players with disabilities -- **Localization Testing** - Regional/cultural validation -- **Competitive Testing** - Balance and meta testing - -## Playtesting Process - -### 1. Define Goals - -Before each playtest session, define: - -- What questions are you trying to answer? -- What features are you testing? -- What metrics will you gather? - -### 2. Prepare the Build - -- Create a stable, playable build -- Include telemetry/logging if needed -- Prepare any necessary documentation - -### 3. Brief Testers - -- Explain what to test (or don't, for blind testing) -- Set expectations for bugs/polish level -- Provide feedback mechanisms - -### 4. Observe and Record - -- Watch players without intervening -- Note confusion points, frustration, delight -- Record gameplay if possible - -### 5. Gather Feedback - -- Structured surveys for quantitative data -- Open discussion for qualitative insights -- Allow time for "what else?" comments - -### 6. Analyze and Act - -- Identify patterns across testers -- Prioritize issues by frequency and severity -- Create actionable tasks from findings - -## Key Metrics to Track - -### Engagement Metrics - -- Session length -- Return rate -- Completion rate -- Drop-off points - -### Difficulty Metrics - -- Deaths/failures per section -- Time to complete sections -- Hint/help usage -- Difficulty setting distribution - -### UX Metrics - -- Time to first action -- Tutorial completion rate -- Menu navigation patterns -- Control scheme preferences - -## Playtesting by Game Type - -Different genres require different playtesting approaches and focus areas. - -### Action/Platformer Games - -**Focus Areas:** - -- Control responsiveness and "game feel" -- Difficulty curve across levels -- Checkpoint placement and frustration points -- Visual clarity during fast-paced action - -**Key Questions:** - -- Does the character feel good to control? -- Are deaths feeling fair or cheap? -- Is the player learning organically or hitting walls? - -### RPG/Story Games - -**Focus Areas:** - -- Narrative pacing and engagement -- Quest clarity and tracking -- Character/dialogue believability -- Progression and reward timing - -**Key Questions:** - -- Do players understand their current objective? -- Are choices feeling meaningful? -- Is the story holding attention or being skipped? - -### Puzzle Games - -**Focus Areas:** - -- Solution discoverability -- "Aha moment" timing -- Hint system effectiveness -- Difficulty progression - -**Key Questions:** - -- Are players solving puzzles the intended way? -- How long before frustration sets in? -- Do solutions feel satisfying or arbitrary? - -### Multiplayer/Competitive Games - -**Focus Areas:** - -- Balance across characters/builds/strategies -- Meta development and dominant strategies -- Social dynamics and toxicity vectors -- Matchmaking feel - -**Key Questions:** - -- Are there "must-pick" or "never-pick" options? -- Do losing players understand why they lost? -- Is the skill ceiling high enough for mastery? - -### Survival/Sandbox Games - -**Focus Areas:** - -- Early game onboarding and survival -- Goal clarity vs. freedom balance -- Resource economy and pacing -- Emergent gameplay moments - -**Key Questions:** - -- Do players know what to do first? -- Is the loop engaging beyond the first hour? -- Are players creating their own goals? - -### Mobile/Casual Games - -**Focus Areas:** - -- Session length appropriateness -- One-hand playability (if applicable) -- Interruption handling (calls, notifications) -- Monetization friction points - -**Key Questions:** - -- Can players play in 2-minute sessions? -- Is the core loop immediately understandable? -- Where do players churn? - -### Horror Games - -**Focus Areas:** - -- Tension and release pacing -- Scare effectiveness and desensitization -- Safe space placement -- Audio/visual atmosphere - -**Key Questions:** - -- When do players feel safe vs. threatened? -- Are scares landing or becoming predictable? -- Is anxiety sustainable or exhausting? - -## Processing Feedback Effectively - -Raw feedback is noise. Processed feedback is signal. - -### The Feedback Processing Pipeline - -``` -Raw Feedback โ†’ Categorize โ†’ Pattern Match โ†’ Root Cause โ†’ Prioritize โ†’ Action -``` - -### Step 1: Categorize Feedback - -Sort all feedback into buckets: - -| Category | Examples | -| ------------- | ---------------------------------- | -| **Bugs** | Crashes, glitches, broken features | -| **Usability** | Confusing UI, unclear objectives | -| **Balance** | Too hard, too easy, unfair | -| **Feel** | Controls, pacing, satisfaction | -| **Content** | Wants more of X, dislikes Y | -| **Polish** | Audio, visuals, juice | - -### Step 2: Pattern Matching - -Individual feedback is anecdotal. Patterns are data. - -**Threshold Guidelines:** - -- 1 person mentions it โ†’ Note it -- 3+ people mention it โ†’ Investigate -- 50%+ mention it โ†’ Priority issue - -**Watch for:** - -- Same complaint, different words -- Same area, different complaints (signals deeper issue) -- Contradictory feedback (may indicate preference split) - -### Step 3: Root Cause Analysis - -Players report symptoms, not diseases. - -**Example:** - -- **Symptom:** "The boss is too hard" -- **Possible Root Causes:** - - Boss mechanics unclear - - Player didn't learn required skill earlier - - Checkpoint too far from boss - - Health/damage tuning off - - Boss pattern has no safe windows - -**Ask "Why?" five times** to get to root cause. - -### Step 4: Separate Fact from Opinion - -| Fact (Actionable) | Opinion (Context) | -| --------------------------------- | ----------------------- | -| "I died 12 times on level 3" | "Level 3 is too hard" | -| "I didn't use the shield ability" | "The shield is useless" | -| "I quit after 20 minutes" | "The game is boring" | - -**Facts tell you WHAT happened. Opinions tell you how they FELT about it.** - -Both matter, but facts drive solutions. - -### Step 5: The Feedback Matrix - -Plot issues on impact vs. effort: - -``` - High Impact - โ”‚ - Quick โ”‚ Major - Wins โ”‚ Projects - โ”‚ -โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - โ”‚ - Fill โ”‚ Reconsider - Time โ”‚ - โ”‚ - Low Impact - Low Effort โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ High Effort -``` - -### Step 6: Validate Before Acting - -Before making changes based on feedback: - -1. **Reproduce** - Can you see the issue yourself? -2. **Quantify** - How many players affected? -3. **Contextualize** - Is this your target audience? -4. **Test solutions** - Will the fix create new problems? - -### Handling Contradictory Feedback - -When Player A wants X and Player B wants the opposite: - -1. **Check sample size** - Is it really split or just 2 loud voices? -2. **Segment audiences** - Are these different player types? -3. **Find the underlying need** - Both may want the same thing differently -4. **Consider options** - Difficulty settings, toggles, multiple paths -5. **Make a decision** - You can't please everyone; know your target - -### Feedback Red Flags - -**Dismiss or investigate carefully:** - -- "Make it like [other game]" - They want a feeling, not a clone -- "Add multiplayer" - Feature creep disguised as feedback -- "I would have bought it if..." - Hypothetical customers aren't real -- Feedback from non-target audience - Know who you're building for - -**Take seriously:** - -- Confusion about core mechanics -- Consistent drop-off at same point -- "I wanted to like it but..." -- Silent quitting (no feedback, just gone) - -### Documentation Best Practices - -**For each playtest session, record:** - -- Date and build version -- Tester demographics/experience -- Session length -- Key observations (timestamped if recorded) -- Quantitative survey results -- Top 3 issues identified -- Actions taken as result - -**Maintain a living document** that tracks: - -- Issue โ†’ First reported โ†’ Times reported โ†’ Status โ†’ Resolution -- This prevents re-discovering the same issues - -## Common Playtesting Pitfalls - -### Leading Questions - -**Bad:** "Did you find the combat exciting?" -**Good:** "How would you describe the combat?" - -### Intervening Too Soon - -Let players struggle before helping. Confusion is valuable data. - -### Testing Too Late - -Start playtesting early with paper prototypes and gray boxes. - -### Ignoring Negative Feedback - -Negative feedback is often the most valuable. Don't dismiss it. - -### Over-Relying on Verbal Feedback - -Watch what players DO, not just what they SAY. Actions reveal truth. - -## Playtesting Checklist - -### Pre-Session - -- [ ] Goals defined -- [ ] Build stable and deployed -- [ ] Recording setup (if applicable) -- [ ] Feedback forms ready -- [ ] Testers briefed - -### During Session - -- [ ] Observing without intervening -- [ ] Taking notes on behavior -- [ ] Tracking time markers for notable moments -- [ ] Noting emotional reactions - -### Post-Session - -- [ ] Feedback collected -- [ ] Patterns identified -- [ ] Priority issues flagged -- [ ] Action items created -- [ ] Results shared with team diff --git a/src/modules/bmgd/gametest/knowledge/qa-automation.md b/src/modules/bmgd/gametest/knowledge/qa-automation.md deleted file mode 100644 index 491660b2..00000000 --- a/src/modules/bmgd/gametest/knowledge/qa-automation.md +++ /dev/null @@ -1,190 +0,0 @@ -# QA Automation for Games - -## Overview - -Automated testing in games requires different approaches than traditional software. Games have complex state, real-time interactions, and subjective quality measures that challenge automation. - -## Testing Pyramid for Games - -``` - /\ - / \ Manual Playtesting - /----\ (Experience, Feel, Fun) - / \ - /--------\ Integration Tests - / \ (Systems, Workflows) - /------------\ - / \ Unit Tests -/________________\ (Pure Logic, Math, Data) -``` - -### Unit Tests (Foundation) - -Test pure logic that doesn't depend on engine runtime: - -- Math utilities (vectors, transforms, curves) -- Data validation (save files, configs) -- State machines (isolated logic) -- Algorithm correctness - -### Integration Tests (Middle Layer) - -Test system interactions: - -- Combat system + inventory -- Save/load round-trips -- Scene transitions -- Network message handling - -### Manual Testing (Top) - -What can't be automated: - -- "Does this feel good?" -- "Is this fun?" -- "Is the difficulty right?" - -## Automation Strategies by Engine - -### Unity - -```csharp -// Unity Test Framework -[Test] -public void DamageCalculation_CriticalHit_DoublesDamage() -{ - var baseDamage = 100; - var result = DamageCalculator.Calculate(baseDamage, isCritical: true); - Assert.AreEqual(200, result); -} - -// Play Mode Tests (runtime) -[UnityTest] -public IEnumerator PlayerJump_WhenGrounded_BecomesAirborne() -{ - var player = CreateTestPlayer(); - player.Jump(); - yield return new WaitForFixedUpdate(); - Assert.IsFalse(player.IsGrounded); -} -``` - -### Unreal Engine - -```cpp -// Automation Framework -IMPLEMENT_SIMPLE_AUTOMATION_TEST(FDamageTest, "Game.Combat.Damage", - EAutomationTestFlags::ApplicationContextMask | EAutomationTestFlags::ProductFilter) - -bool FDamageTest::RunTest(const FString& Parameters) -{ - float BaseDamage = 100.f; - float Result = UDamageCalculator::Calculate(BaseDamage, true); - TestEqual("Critical hit doubles damage", Result, 200.f); - return true; -} -``` - -### Godot - -```gdscript -# GUT Testing Framework -func test_damage_critical_hit(): - var base_damage = 100 - var result = DamageCalculator.calculate(base_damage, true) - assert_eq(result, 200, "Critical hit should double damage") -``` - -## What to Automate - -### High Value Targets - -- **Save/Load** - Data integrity is critical -- **Economy** - Currency, items, progression math -- **Combat Math** - Damage, stats, modifiers -- **Localization** - String loading, formatting -- **Network Serialization** - Message encoding/decoding - -### Medium Value Targets - -- **State Machines** - Character states, game states -- **Pathfinding** - Known scenarios -- **Spawning** - Wave generation, loot tables -- **UI Data Binding** - Correct values displayed - -### Low Value / Avoid - -- **Visual Quality** - Screenshots drift, hard to maintain -- **Input Feel** - Timing-sensitive, needs human judgment -- **Audio** - Subjective, context-dependent -- **Fun** - Cannot be automated - -## Continuous Integration for Games - -### Build Pipeline - -1. **Compile** - Build game executable -2. **Unit Tests** - Fast, isolated tests -3. **Integration Tests** - Longer, system tests -4. **Smoke Test** - Can the game launch and reach main menu? -5. **Nightly** - Extended test suites, performance benchmarks - -### CI Gotchas for Games - -- **Long build times** - Games take longer than web apps -- **GPU requirements** - Some tests need graphics hardware -- **Asset dependencies** - Large files, binary formats -- **Platform builds** - Multiple targets to maintain - -## Regression Testing - -### Automated Regression - -- Run full test suite on every commit -- Flag performance regressions (frame time, memory) -- Track test stability (flaky tests) - -### Save File Regression - -- Maintain library of save files from previous versions -- Test that new builds can load old saves -- Alert on schema changes - -## Test Data Management - -### Test Fixtures - -``` -tests/ -โ”œโ”€โ”€ fixtures/ -โ”‚ โ”œโ”€โ”€ save_files/ -โ”‚ โ”‚ โ”œโ”€โ”€ new_game.sav -โ”‚ โ”‚ โ”œโ”€โ”€ mid_game.sav -โ”‚ โ”‚ โ””โ”€โ”€ endgame.sav -โ”‚ โ”œโ”€โ”€ configs/ -โ”‚ โ”‚ โ””โ”€โ”€ test_balance.json -โ”‚ โ””โ”€โ”€ scenarios/ -โ”‚ โ””โ”€โ”€ boss_fight_setup.scene -``` - -### Deterministic Testing - -- Seed random number generators -- Control time/delta time -- Mock external services - -## Metrics and Reporting - -### Track Over Time - -- Test count (growing is good) -- Pass rate (should be ~100%) -- Execution time (catch slow tests) -- Code coverage (where applicable) -- Flaky test rate (should be ~0%) - -### Alerts - -- Immediate: Any test failure on main branch -- Daily: Coverage drops, new flaky tests -- Weekly: Trend analysis, slow test growth diff --git a/src/modules/bmgd/gametest/knowledge/regression-testing.md b/src/modules/bmgd/gametest/knowledge/regression-testing.md deleted file mode 100644 index 975c4659..00000000 --- a/src/modules/bmgd/gametest/knowledge/regression-testing.md +++ /dev/null @@ -1,280 +0,0 @@ -# Regression Testing for Games - -## Overview - -Regression testing catches bugs introduced by new changes. In games, this includes functional regressions, performance regressions, and design regressions. - -## Types of Regression - -### Functional Regression - -- Features that worked before now break -- New bugs introduced by unrelated changes -- Broken integrations between systems - -### Performance Regression - -- Frame rate drops -- Memory usage increases -- Load time increases -- Battery drain (mobile) - -### Design Regression - -- Balance changes with unintended side effects -- UX changes that hurt usability -- Art changes that break visual consistency - -### Save Data Regression - -- Old save files no longer load -- Progression lost or corrupted -- Achievements/unlocks reset - -## Regression Testing Strategy - -### Test Suite Layers - -``` -High-Frequency (Every Commit) -โ”œโ”€โ”€ Unit Tests - Fast, isolated -โ”œโ”€โ”€ Smoke Tests - Can game launch and run? -โ””โ”€โ”€ Critical Path - Core gameplay works - -Medium-Frequency (Nightly) -โ”œโ”€โ”€ Integration Tests - System interactions -โ”œโ”€โ”€ Full Playthrough - Automated or manual -โ””โ”€โ”€ Performance Benchmarks - Frame time, memory - -Low-Frequency (Release) -โ”œโ”€โ”€ Full Matrix - All platforms/configs -โ”œโ”€โ”€ Certification Tests - Platform requirements -โ””โ”€โ”€ Localization - All languages -``` - -### What to Test - -#### Critical Path (Must Not Break) - -- Game launches -- New game starts -- Save/load works -- Core gameplay loop completes -- Main menu navigation - -#### High Priority - -- All game systems function -- Progression works end-to-end -- Multiplayer connects and syncs -- In-app purchases process -- Achievements trigger - -#### Medium Priority - -- Edge cases in systems -- Optional content accessible -- Settings persist correctly -- Localization displays - -## Automated Regression Tests - -### Smoke Tests - -```python -# Run on every commit -def test_game_launches(): - process = launch_game() - assert wait_for_main_menu(timeout=30) - process.terminate() - -def test_new_game_starts(): - launch_game() - click_new_game() - assert wait_for_gameplay(timeout=60) - -def test_save_load_roundtrip(): - launch_game() - start_new_game() - perform_actions() - save_game() - load_game() - assert verify_state_matches() -``` - -### Playthrough Bots - -```python -# Automated player that plays through content -class PlaythroughBot: - def run_level(self, level): - self.load_level(level) - while not self.level_complete: - self.perform_action() - self.check_for_softlocks() - self.record_metrics() -``` - -### Visual Regression - -```python -# Compare screenshots against baselines -def test_main_menu_visual(): - launch_game() - screenshot = capture_screen() - assert compare_to_baseline(screenshot, 'main_menu', threshold=0.01) -``` - -## Performance Regression Detection - -### Metrics to Track - -- Average frame time -- 1% low frame time -- Memory usage (peak, average) -- Load times -- Draw calls -- Texture memory - -### Automated Benchmarks - -```yaml -performance_benchmark: - script: - - run_benchmark_scene --duration 60s - - collect_metrics - - compare_to_baseline - fail_conditions: - - frame_time_avg > baseline * 1.1 # 10% tolerance - - memory_peak > baseline * 1.05 # 5% tolerance -``` - -### Trend Tracking - -- Graph metrics over time -- Alert on upward trends -- Identify problematic commits - -## Save Compatibility Testing - -### Version Matrix - -Maintain save files from: - -- Previous major version -- Previous minor version -- Current development build - -### Automated Validation - -```python -def test_save_compatibility(): - for save_file in LEGACY_SAVES: - load_save(save_file) - assert no_errors() - assert progress_preserved() - assert inventory_intact() -``` - -### Schema Versioning - -- Version your save format -- Implement upgrade paths -- Log migration issues - -## Regression Bug Workflow - -### 1. Detection - -- Automated test fails -- Manual tester finds issue -- Player report comes in - -### 2. Verification - -- Confirm it worked before -- Identify when it broke -- Find the breaking commit - -### 3. Triage - -- Assess severity -- Determine fix urgency -- Assign to appropriate developer - -### 4. Fix and Verify - -- Implement fix -- Add regression test -- Verify fix doesn't break other things - -### 5. Post-Mortem - -- Why wasn't this caught? -- How can we prevent similar issues? -- Do we need new tests? - -## Bisecting Regressions - -When a regression is found, identify the breaking commit: - -### Git Bisect - -```bash -git bisect start -git bisect bad HEAD # Current is broken -git bisect good v1.2.0 # Known good version -# Git will checkout commits to test -# Run test, mark good/bad -git bisect good/bad -# Repeat until culprit found -``` - -### Automated Bisect - -```bash -git bisect start HEAD v1.2.0 -git bisect run ./run_regression_test.sh -``` - -## Regression Testing Checklist - -### Per Commit - -- [ ] Unit tests pass -- [ ] Smoke tests pass -- [ ] Build succeeds on all platforms - -### Per Merge to Main - -- [ ] Integration tests pass -- [ ] Performance benchmarks within tolerance -- [ ] Save compatibility verified - -### Per Release - -- [ ] Full playthrough completed -- [ ] All platforms tested -- [ ] Legacy saves load correctly -- [ ] No new critical regressions -- [ ] All previous hotfix issues still resolved - -## Building a Regression Suite - -### Start Small - -1. Add tests for bugs as they're fixed -2. Cover critical path first -3. Expand coverage over time - -### Maintain Quality - -- Delete flaky tests -- Keep tests fast -- Update tests with design changes - -### Measure Effectiveness - -- Track bugs caught by tests -- Track bugs that slipped through -- Identify coverage gaps diff --git a/src/modules/bmgd/gametest/knowledge/save-testing.md b/src/modules/bmgd/gametest/knowledge/save-testing.md deleted file mode 100644 index 663898a5..00000000 --- a/src/modules/bmgd/gametest/knowledge/save-testing.md +++ /dev/null @@ -1,280 +0,0 @@ -# Save System Testing Guide - -## Overview - -Save system testing ensures data persistence, integrity, and compatibility across game versions. Save bugs are among the most frustrating for playersโ€”data loss destroys trust. - -## Test Categories - -### Data Integrity - -| Test Type | Description | Priority | -| -------------------- | ------------------------------------------- | -------- | -| Round-trip | Save โ†’ Load โ†’ Verify all data matches | P0 | -| Corruption detection | Tampered/corrupted files handled gracefully | P0 | -| Partial write | Power loss during save doesn't corrupt | P0 | -| Large saves | Performance with max-size save files | P1 | -| Edge values | Min/max values for all saved fields | P1 | - -### Version Compatibility - -| Scenario | Expected Behavior | -| ----------------------- | ------------------------------------- | -| Current โ†’ Current | Full compatibility | -| Old โ†’ New (upgrade) | Migration with data preservation | -| New โ†’ Old (downgrade) | Graceful rejection or limited support | -| Corrupted version field | Fallback to recovery mode | - -## Test Scenarios - -### Core Save/Load Tests - -``` -SCENARIO: Basic Save Round-Trip - GIVEN player has 100 health, 50 gold, position (10, 5, 20) - AND player has inventory: ["sword", "potion", "key"] - WHEN game is saved - AND game is reloaded - THEN player health equals 100 - AND player gold equals 50 - AND player position equals (10, 5, 20) - AND inventory contains exactly ["sword", "potion", "key"] - -SCENARIO: Save During Gameplay - GIVEN player is in combat - AND enemy has 50% health remaining - WHEN autosave triggers - AND game is reloaded - THEN combat state is restored - AND enemy health equals 50% - -SCENARIO: Multiple Save Slots - GIVEN save slot 1 has character "Hero" at level 10 - AND save slot 2 has character "Mage" at level 5 - WHEN switching between slots - THEN correct character data loads for each slot - AND no cross-contamination between slots -``` - -### Edge Cases - -``` -SCENARIO: Maximum Inventory Save - GIVEN player has 999 items in inventory - WHEN game is saved - AND game is reloaded - THEN all 999 items are preserved - AND save/load completes within 5 seconds - -SCENARIO: Unicode Character Names - GIVEN player name is "ใƒ—ใƒฌใ‚คใƒคใƒผๅ" - WHEN game is saved - AND game is reloaded - THEN player name displays correctly - -SCENARIO: Extreme Play Time - GIVEN play time is 9999:59:59 - WHEN game is saved - AND game is reloaded - THEN play time displays correctly - AND timer continues from saved value -``` - -### Corruption Recovery - -``` -SCENARIO: Corrupted Save Detection - GIVEN save file has been manually corrupted - WHEN game attempts to load - THEN error is detected before loading - AND user is informed of corruption - AND game does not crash - -SCENARIO: Missing Save File - GIVEN save file has been deleted externally - WHEN game attempts to load - THEN graceful error handling - AND option to start new game or restore backup - -SCENARIO: Interrupted Save (Power Loss) - GIVEN save operation is interrupted mid-write - WHEN game restarts - THEN backup save is detected and offered - AND no data loss from previous valid save -``` - -## Platform-Specific Testing - -### PC (Steam/Epic) - -- Cloud save sync conflicts -- Multiple Steam accounts on same PC -- Offline โ†’ Online sync -- Save location permissions (Program Files issues) - -### Console (PlayStation/Xbox/Switch) - -- System-level save management -- Storage full scenarios -- User switching mid-game -- Suspend/resume with unsaved changes -- Cloud save quota limits - -### Mobile - -- App termination during save -- Low storage warnings -- iCloud/Google Play sync -- Device migration - -## Automated Test Examples - -### Unity - -```csharp -[Test] -public void SaveLoad_PlayerStats_PreservesAllValues() -{ - var original = new PlayerData - { - Health = 75, - MaxHealth = 100, - Gold = 1234567, - Position = new Vector3(100.5f, 0, -50.25f), - PlayTime = 36000f // 10 hours - }; - - SaveManager.Save(original, "test_slot"); - var loaded = SaveManager.Load("test_slot"); - - Assert.AreEqual(original.Health, loaded.Health); - Assert.AreEqual(original.Gold, loaded.Gold); - Assert.AreEqual(original.Position, loaded.Position); - Assert.AreEqual(original.PlayTime, loaded.PlayTime, 0.01f); -} - -[Test] -public void SaveLoad_CorruptedFile_HandlesGracefully() -{ - File.WriteAllText(SaveManager.GetPath("corrupt"), "INVALID DATA"); - - Assert.Throws(() => - SaveManager.Load("corrupt")); - - // Game should not crash - Assert.IsTrue(SaveManager.IsValidSaveSlot("corrupt") == false); -} -``` - -### Unreal - -```cpp -bool FSaveSystemTest::RunTest(const FString& Parameters) -{ - // Create test save - USaveGame* SaveGame = UGameplayStatics::CreateSaveGameObject( - UMySaveGame::StaticClass()); - UMySaveGame* MySave = Cast(SaveGame); - - MySave->PlayerLevel = 50; - MySave->Gold = 999999; - MySave->QuestsCompleted = {"Quest1", "Quest2", "Quest3"}; - - // Save - UGameplayStatics::SaveGameToSlot(MySave, "TestSlot", 0); - - // Load - USaveGame* Loaded = UGameplayStatics::LoadGameFromSlot("TestSlot", 0); - UMySaveGame* LoadedSave = Cast(Loaded); - - TestEqual("Level preserved", LoadedSave->PlayerLevel, 50); - TestEqual("Gold preserved", LoadedSave->Gold, 999999); - TestEqual("Quests count", LoadedSave->QuestsCompleted.Num(), 3); - - return true; -} -``` - -### Godot - -```gdscript -func test_save_load_round_trip(): - var original = { - "health": 100, - "position": Vector3(10, 0, 20), - "inventory": ["sword", "shield"], - "quest_flags": {"intro_complete": true, "boss_defeated": false} - } - - SaveManager.save_game(original, "test_save") - var loaded = SaveManager.load_game("test_save") - - assert_eq(loaded.health, 100) - assert_eq(loaded.position, Vector3(10, 0, 20)) - assert_eq(loaded.inventory.size(), 2) - assert_true(loaded.quest_flags.intro_complete) - assert_false(loaded.quest_flags.boss_defeated) - -func test_corrupted_save_detection(): - var file = FileAccess.open("user://saves/corrupt.sav", FileAccess.WRITE) - file.store_string("CORRUPTED GARBAGE DATA") - file.close() - - var result = SaveManager.load_game("corrupt") - - assert_null(result, "Should return null for corrupted save") - assert_false(SaveManager.is_valid_save("corrupt")) -``` - -## Migration Testing - -### Version Upgrade Matrix - -| From Version | To Version | Test Focus | -| -------------- | ---------------- | ---------------------------- | -| 1.0 โ†’ 1.1 | Minor update | New fields default correctly | -| 1.x โ†’ 2.0 | Major update | Schema migration works | -| Beta โ†’ Release | Launch migration | All beta saves convert | - -### Migration Test Template - -``` -SCENARIO: Save Migration v1.0 to v2.0 - GIVEN save file from version 1.0 - AND save contains old inventory format (array) - WHEN game version 2.0 loads the save - THEN inventory is migrated to new format (dictionary) - AND all items are preserved - AND migration is logged - AND backup of original is created -``` - -## Performance Benchmarks - -| Metric | Target | Maximum | -| ------------------------ | --------------- | ------- | -| Save time (typical) | < 500ms | 2s | -| Save time (large) | < 2s | 5s | -| Load time (typical) | < 1s | 3s | -| Save file size (typical) | < 1MB | 10MB | -| Memory during save | < 50MB overhead | 100MB | - -## Best Practices - -### DO - -- Use atomic saves (write to temp, then rename) -- Keep backup of previous save -- Version your save format -- Encrypt sensitive data -- Test on minimum-spec hardware -- Compress large saves - -### DON'T - -- Store absolute file paths -- Save derived/calculated data -- Trust save file contents blindly -- Block gameplay during save -- Forget to handle storage-full scenarios -- Skip testing save migration paths diff --git a/src/modules/bmgd/gametest/knowledge/smoke-testing.md b/src/modules/bmgd/gametest/knowledge/smoke-testing.md deleted file mode 100644 index 20be2ae0..00000000 --- a/src/modules/bmgd/gametest/knowledge/smoke-testing.md +++ /dev/null @@ -1,404 +0,0 @@ -# Smoke Testing Guide - -## Overview - -Smoke testing (Build Verification Testing) validates that a build's critical functionality works before investing time in detailed testing. A failed smoke test means "stop, this build is broken." - -## Purpose - -| Goal | Description | -| ------------------- | ---------------------------------------------- | -| Fast feedback | Know within minutes if build is viable | -| Block bad builds | Prevent broken builds from reaching QA/players | -| Critical path focus | Test only what matters most | -| CI/CD integration | Automated gate before deployment | - -## Smoke Test Principles - -### What Makes a Good Smoke Test - -- **Fast**: Complete in 5-15 minutes -- **Critical**: Tests only essential functionality -- **Deterministic**: Same result every run -- **Automated**: No human intervention required -- **Clear**: Pass/fail with actionable feedback - -### What to Include - -| Category | Examples | -| ----------------- | ------------------------------ | -| Boot sequence | Game launches without crash | -| Core loop | Player can perform main action | -| Save/Load | Data persists correctly | -| Critical UI | Menus are navigable | -| Platform services | Connects to required services | - -### What NOT to Include - -- Edge cases and boundary conditions -- Performance benchmarks (separate tests) -- Full feature coverage -- Content verification -- Balance testing - -## Smoke Test Scenarios - -### Boot and Load - -``` -TEST: Game Launches - WHEN game executable is started - THEN main menu appears within 60 seconds - AND no crashes occur - AND required services connect - -TEST: New Game Start - GIVEN game at main menu - WHEN "New Game" is selected - THEN gameplay loads within 30 seconds - AND player can control character - -TEST: Continue Game - GIVEN existing save file - WHEN "Continue" is selected - THEN correct save loads - AND game state matches saved state -``` - -### Core Gameplay - -``` -TEST: Player Movement - GIVEN player in game world - WHEN movement input applied - THEN player moves in expected direction - AND no physics glitches occur - -TEST: Core Action (Game-Specific) - GIVEN player can perform primary action - WHEN action is triggered - THEN action executes correctly - AND expected results occur - - Examples: - - Shooter: Can fire weapon, bullets hit targets - - RPG: Can attack enemy, damage is applied - - Puzzle: Can interact with puzzle elements - - Platformer: Can jump, platforms are solid -``` - -### Save System - -``` -TEST: Save Creates File - GIVEN player makes progress - WHEN save is triggered - THEN save file is created - AND save completes without error - -TEST: Load Restores State - GIVEN valid save file exists - WHEN load is triggered - THEN saved state is restored - AND gameplay can continue -``` - -### Critical UI - -``` -TEST: Menu Navigation - GIVEN main menu is displayed - WHEN each menu option is selected - THEN correct screen/action occurs - AND navigation back works - -TEST: Settings Persist - GIVEN settings are changed - WHEN game is restarted - THEN settings remain changed -``` - -## Automated Smoke Test Examples - -### Unity - -```csharp -using System.Collections; -using NUnit.Framework; -using UnityEngine; -using UnityEngine.UI; -using UnityEngine.TestTools; -using UnityEngine.SceneManagement; - -[TestFixture] -public class SmokeTests -{ - [UnityTest, Timeout(60000)] - public IEnumerator Game_Launches_ToMainMenu() - { - // Load main menu scene - SceneManager.LoadScene("MainMenu"); - yield return new WaitForSeconds(5f); - - // Verify menu is active - var mainMenu = GameObject.Find("MainMenuCanvas"); - Assert.IsNotNull(mainMenu, "Main menu should be present"); - Assert.IsTrue(mainMenu.activeInHierarchy, "Main menu should be active"); - } - - [UnityTest, Timeout(120000)] - public IEnumerator NewGame_LoadsGameplay() - { - // Start from main menu - SceneManager.LoadScene("MainMenu"); - yield return new WaitForSeconds(2f); - - // Click new game - var newGameButton = GameObject.Find("NewGameButton") - .GetComponent