opencode-skills-collection 4.0.53 → 4.0.55

package/bundled-skills/terraform-skill/references/detailed-guide.md

@@ -0,0 +1,430 @@
+# Terraform Skill for Claude - Detailed Guide
+
+> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.
+
+## Core Principles
+
+### 1. Code Structure Philosophy
+
+**Module Hierarchy:**
+
+| Type | When to Use | Scope |
+|------|-------------|-------|
+| **Resource Module** | Single logical group of connected resources | VPC + subnets, Security group + rules |
+| **Infrastructure Module** | Collection of resource modules for a purpose | Multiple resource modules in one region/account |
+| **Composition** | Complete infrastructure | Spans multiple regions/accounts |
+
+**Hierarchy:** Resource → Resource Module → Infrastructure Module → Composition
+
+**Directory Structure:**
+```
+environments/        # Environment-specific configurations
+├── prod/
+├── staging/
+└── dev/
+
+modules/            # Reusable modules
+├── networking/
+├── compute/
+└── data/
+
+examples/           # Module usage examples (also serve as tests)
+├── complete/
+└── minimal/
+```
+
+**Key principle from terraform-best-practices.com:**
+- Separate **environments** (prod, staging) from **modules** (reusable components)
+- Use **examples/** as both documentation and integration test fixtures
+- Keep modules small and focused (single responsibility)
+
+**For detailed module architecture, see:** Code Patterns: Module Types & Hierarchy
+
+### 2. Naming Conventions
+
+**Resources:**
+```hcl
+# Good: Descriptive, contextual
+resource "aws_instance" "web_server" { }
+resource "aws_s3_bucket" "application_logs" { }
+
+# Good: "this" for singleton resources (only one of that type)
+resource "aws_vpc" "this" { }
+resource "aws_security_group" "this" { }
+
+# Avoid: Generic names for non-singletons
+resource "aws_instance" "main" { }
+resource "aws_s3_bucket" "bucket" { }
+```
+
+**Singleton Resources:**
+
+Use `"this"` when your module creates only one resource of that type:
+
+✅ DO:
+```hcl
+resource "aws_vpc" "this" {}           # Module creates one VPC
+resource "aws_security_group" "this" {}  # Module creates one SG
+```
+
+❌ DON'T use "this" for multiple resources:
+```hcl
+resource "aws_subnet" "this" {}  # If creating multiple subnets
+```
+
+Use descriptive names when creating multiple resources of the same type.
+
+**Variables:**
+```hcl
+# Prefix with context when needed
+var.vpc_cidr_block          # Not just "cidr"
+var.database_instance_class # Not just "instance_class"
+```
+
+**Files:**
+- `main.tf` - Primary resources
+- `variables.tf` - Input variables
+- `outputs.tf` - Output values
+- `versions.tf` - Provider versions
+- `data.tf` - Data sources (optional)
+
+
+## Testing Strategy Framework
+
+### Decision Matrix: Which Testing Approach?
+
+| Your Situation | Recommended Approach | Tools | Cost |
+|----------------|---------------------|-------|------|
+| **Quick syntax check** | Static analysis | `terraform validate`, `fmt` | Free |
+| **Pre-commit validation** | Static + lint | `validate`, `tflint`, `trivy`, `checkov` | Free |
+| **Terraform 1.6+, simple logic** | Native test framework | Built-in `terraform test` | Free-Low |
+| **Pre-1.6, or Go expertise** | Integration testing | Terratest | Low-Med |
+| **Security/compliance focus** | Policy as code | OPA, Sentinel | Free |
+| **Cost-sensitive workflow** | Mock providers (1.7+) | Native tests + mocking | Free |
+| **Multi-cloud, complex** | Full integration | Terratest + real infra | Med-High |
+
+### Testing Pyramid for Infrastructure
+
+```
+        /\
+       /  \          End-to-End Tests (Expensive)
+      /____\         - Full environment deployment
+     /      \        - Production-like setup
+    /________\
+   /          \      Integration Tests (Moderate)
+  /____________\     - Module testing in isolation
+ /              \    - Real resources in test account
+/________________\   Static Analysis (Cheap)
+                     - validate, fmt, lint
+                     - Security scanning
+```
+
+### Native Test Best Practices (1.6+)
+
+**Before generating test code:**
+
+1. **Validate schemas with Terraform MCP:**
+   ```
+   Search provider docs → Get resource schema → Identify block types
+   ```
+
+2. **Choose correct command mode:**
+   - `command = plan` - Fast, for input validation
+   - `command = apply` - Required for computed values and set-type blocks
+
+3. **Handle set-type blocks correctly:**
+   - Cannot index with `[0]`
+   - Use `for` expressions to iterate
+   - Or use `command = apply` to materialize
+
+**Common patterns:**
+- S3 encryption rules: **set** (use for expressions)
+- Lifecycle transitions: **set** (use for expressions)
+- IAM policy statements: **set** (use for expressions)
+
+**For detailed testing guides, see:**
+- **Testing Frameworks Guide** - Deep dive into static analysis, native tests, and Terratest
+- **Quick Reference** - Decision flowchart and command cheat sheet
+
+
+## Code Structure Standards
+
+### Resource Block Ordering
+
+**Strict ordering for consistency:**
+1. `count` or `for_each` FIRST (blank line after)
+2. Other arguments
+3. `tags` as last real argument
+4. `depends_on` after tags (if needed)
+5. `lifecycle` at the very end (if needed)
+
+```hcl
+# ✅ GOOD - Correct ordering
+resource "aws_nat_gateway" "this" {
+  count = var.create_nat_gateway ? 1 : 0
+
+  allocation_id = aws_eip.this[0].id
+  subnet_id     = aws_subnet.public[0].id
+
+  tags = {
+    Name = "${var.name}-nat"
+  }
+
+  depends_on = [aws_internet_gateway.this]
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+```
+
+### Variable Block Ordering
+
+1. `description` (ALWAYS required)
+2. `type`
+3. `default`
+4. `validation`
+5. `nullable` (when setting to false)
+
+```hcl
+variable "environment" {
+  description = "Environment name for resource tagging"
+  type        = string
+  default     = "dev"
+
+  validation {
+    condition     = contains(["dev", "staging", "prod"], var.environment)
+    error_message = "Environment must be one of: dev, staging, prod."
+  }
+
+  nullable = false
+}
+```
+
+**For complete structure guidelines, see:** Code Patterns: Block Ordering & Structure
+
+
+## Locals for Dependency Management
+
+**Use locals to ensure correct resource deletion order:**
+
+```hcl
+# Problem: Subnets might be deleted after CIDR blocks, causing errors
+# Solution: Use try() in locals to hint deletion order
+
+locals {
+  # References secondary CIDR first, falling back to VPC
+  # Forces Terraform to delete subnets before CIDR association
+  vpc_id = try(
+    aws_vpc_ipv4_cidr_block_association.this[0].vpc_id,
+    aws_vpc.this.id,
+    ""
+  )
+}
+
+resource "aws_vpc" "this" {
+  cidr_block = "10.0.0.0/16"
+}
+
+resource "aws_vpc_ipv4_cidr_block_association" "this" {
+  count = var.add_secondary_cidr ? 1 : 0
+
+  vpc_id     = aws_vpc.this.id
+  cidr_block = "10.1.0.0/16"
+}
+
+resource "aws_subnet" "public" {
+  vpc_id     = local.vpc_id  # Uses local, not direct reference
+  cidr_block = "10.1.0.0/24"
+}
+```
+
+**Why this matters:**
+- Prevents deletion errors when destroying infrastructure
+- Ensures correct dependency order without explicit `depends_on`
+- Particularly useful for VPC configurations with secondary CIDR blocks
+
+**For detailed examples, see:** Code Patterns: Locals for Dependency Management
+
+
+## Module Development
+
+### Standard Module Structure
+
+```
+my-module/
+├── README.md           # Usage documentation
+├── main.tf             # Primary resources
+├── variables.tf        # Input variables with descriptions
+├── outputs.tf          # Output values
+├── versions.tf         # Provider version constraints
+├── examples/
+│   ├── minimal/        # Minimal working example
+│   └── complete/       # Full-featured example
+└── tests/              # Test files
+    └── module_test.tftest.hcl  # Or .go
+```
+
+### Best Practices Summary
+
+**Variables:**
+- ✅ Always include `description`
+- ✅ Use explicit `type` constraints
+- ✅ Provide sensible `default` values where appropriate
+- ✅ Add `validation` blocks for complex constraints
+- ✅ Use `sensitive = true` for secrets
+
+**Outputs:**
+- ✅ Always include `description`
+- ✅ Mark sensitive outputs with `sensitive = true`
+- ✅ Consider returning objects for related values
+- ✅ Document what consumers should do with each output
+
+**For detailed module patterns, see:**
+- **Module Patterns Guide** - Variable best practices, output design, ✅ DO vs ❌ DON'T patterns
+- **Quick Reference** - Resource naming, variable naming, file organization
+
+
+## CI/CD Integration
+
+### Recommended Workflow Stages
+
+1. **Validate** - Format check + syntax validation + linting
+2. **Test** - Run automated tests (native or Terratest)
+3. **Plan** - Generate and review execution plan
+4. **Apply** - Execute changes (with approvals for production)
+
+### Cost Optimization Strategy
+
+1. **Use mocking for PR validation** (free)
+2. **Run integration tests only on main branch** (controlled cost)
+3. **Implement auto-cleanup** (prevent orphaned resources)
+4. **Tag all test resources** (track spending)
+
+**For complete CI/CD templates, see:**
+- **CI/CD Workflows Guide** - GitHub Actions, GitLab CI, Atlantis integration, cost optimization
+- **Quick Reference** - Common CI/CD issues and solutions
+
+
+## Version Management
+
+### Version Constraint Syntax
+
+```hcl
+version = "5.0.0"      # Exact (avoid - inflexible)
+version = "~> 5.0"     # Recommended: 5.0.x only
+version = ">= 5.0"     # Minimum (risky - breaking changes)
+```
+
+### Strategy by Component
+
+| Component | Strategy | Example |
+|-----------|----------|---------|
+| **Terraform** | Pin minor version | `required_version = "~> 1.9"` |
+| **Providers** | Pin major version | `version = "~> 5.0"` |
+| **Modules (prod)** | Pin exact version | `version = "5.1.2"` |
+| **Modules (dev)** | Allow patch updates | `version = "~> 5.1"` |
+
+### Update Workflow
+
+```bash
+# Lock versions initially
+terraform init              # Creates .terraform.lock.hcl
+
+# Update to latest within constraints
+terraform init -upgrade     # Updates providers
+
+# Review and test
+terraform plan
+```
+
+**For detailed version management, see:** Code Patterns: Version Management
+
+
+## Modern Terraform Features (1.0+)
+
+### Feature Availability by Version
+
+| Feature | Version | Use Case |
+|---------|---------|----------|
+| `try()` function | 0.13+ | Safe fallbacks, replaces `element(concat())` |
+| `nullable = false` | 1.1+ | Prevent null values in variables |
+| `moved` blocks | 1.1+ | Refactor without destroy/recreate |
+| `optional()` with defaults | 1.3+ | Optional object attributes |
+| Native testing | 1.6+ | Built-in test framework |
+| Mock providers | 1.7+ | Cost-free unit testing |
+| Provider functions | 1.8+ | Provider-specific data transformation |
+| Cross-variable validation | 1.9+ | Validate relationships between variables |
+| Write-only arguments | 1.11+ | Secrets never stored in state |
+
+### Quick Examples
+
+```hcl
+# try() - Safe fallbacks (0.13+)
+output "sg_id" {
+  value = try(aws_security_group.this[0].id, "")
+}
+
+# optional() - Optional attributes with defaults (1.3+)
+variable "config" {
+  type = object({
+    name    = string
+    timeout = optional(number, 300)  # Default: 300
+  })
+}
+
+# Cross-variable validation (1.9+)
+variable "environment" { type = string }
+variable "backup_days" {
+  type = number
+  validation {
+    condition     = var.environment == "prod" ? var.backup_days >= 7 : true
+    error_message = "Production requires backup_days >= 7"
+  }
+}
+```
+
+**For complete patterns and examples, see:** Code Patterns: Modern Terraform Features
+
+
+## Version-Specific Guidance
+
+### Terraform 1.0-1.5
+- Use Terratest for testing
+- No native testing framework available
+- Focus on static analysis and plan validation
+
+### Terraform 1.6+ / OpenTofu 1.6+
+- **New:** Native `terraform test` / `tofu test` command
+- Consider migrating from external frameworks for simple tests
+- Keep Terratest only for complex integration tests
+
+### Terraform 1.7+ / OpenTofu 1.7+
+- **New:** Mock providers for unit testing
+- Reduce cost by mocking external dependencies
+- Use real integration tests for final validation
+
+### Terraform vs OpenTofu
+
+Both are fully supported by this skill. For licensing, governance, and feature comparison, see Quick Reference: Terraform vs OpenTofu.
+
+
+## Detailed Guides
+
+This skill uses **progressive disclosure** - essential information is in this main file, detailed guides are available when needed:
+
+📚 **Reference Files:**
+- **Testing Frameworks** - In-depth guide to static analysis, native tests, and Terratest
+- **Module Patterns** - Module structure, variable/output best practices, ✅ DO vs ❌ DON'T patterns
+- **CI/CD Workflows** - GitHub Actions, GitLab CI templates, cost optimization, automated cleanup
+- **Security & Compliance** - Trivy/Checkov integration, secrets management, compliance testing
+- **Quick Reference** - Command cheat sheets, decision flowcharts, troubleshooting guide
+
+**How to use:** When you need detailed information on a topic, reference the appropriate guide. Claude will load it on demand to provide comprehensive guidance.
+
+
+## License
+
+This skill is licensed under the **Apache License 2.0**. See the LICENSE file for full terms.
+
+**Copyright © 2026 Anton Babenko**

package/bundled-skills/test-driven-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-driven-development
-description: "Use when implementing any feature or bugfix, before writing implementation code"
+description: "Use a failing behavioral test to guide a feature or bug fix, then implement and refactor with relevant regression checks."
 risk: critical
 source: community
 date_added: "2026-02-27"
@@ -17,34 +17,12 @@ Write the test first. Watch it fail. Write minimal code to pass.
 **Violating the letter of the rules is violating the spirit of the rules.**
 
 ## When to Use
-**Always:**
-- New features
-- Bug fixes
-- Refactoring
-- Behavior changes
 
-**Exceptions (ask your human partner):**
-- Throwaway prototypes
-- Generated code
-- Configuration files
+Use for behavior changes where a repeatable test can demonstrate the requirement or reproduce the bug. Inspect the repository’s test runner and existing coverage first. For copy, generated outputs or low-impact configuration, use the appropriate focused validation rather than manufacturing a unit test.
 
-Thinking "skip TDD just this once"? Stop. That's rationalization.
+## Preserve existing work
 
-## The Iron Law
-
-```
-NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
-```
-
-Write code before the test? Delete it. Start over.
-
-**No exceptions:**
-- Don't keep it as "reference"
-- Don't "adapt" it while writing tests
-- Don't look at it
-- Delete means delete
-
-Implement fresh from tests. Period.
+Write the failing regression before the repair when feasible, and verify that it fails for the expected reason. If implementation already exists, preserve it and add characterization/regression tests. Do not delete user work, reset a branch or rewrite working code to reconstruct an ideal test-first history. State honestly whether the test preceded the fix.
 
 ## Red-Green-Refactor
 
@@ -76,9 +54,9 @@ Write one minimal test showing what should happen.
 
 <Good>
 ```typescript
-test('retries failed operations 3 times', async () => {
+test('succeeds on the third attempt', async () => {
   let attempts = 0;
-  const operation = () => {
+  const operation = async () => {
     attempts++;
     if (attempts < 3) throw new Error('fail');
     return 'success';
@@ -125,7 +103,7 @@ Confirm:
 - Failure message is expected
 - Fails because feature missing (not typos)
 
-**Test passes?** You're testing existing behavior. Fix test.
+**Test passes?** Determine whether it already characterizes the required behavior. For a regression, prove it detects the defect using the prior revision or an isolated controlled change; do not alter a correct assertion just to force red.
 
 **Test errors?** Fix error, re-run until it fails correctly.
 
@@ -205,89 +183,11 @@ Next failing test for next feature.
 | **Clear** | Name describes behavior | `test('test1')` |
 | **Shows intent** | Demonstrates desired API | Obscures what code should do |
 
-## Why Order Matters
-
-**"I'll write tests after to verify it works"**
-
-Tests written after code pass immediately. Passing immediately proves nothing:
-- Might test wrong thing
-- Might test implementation, not behavior
-- Might miss edge cases you forgot
-- You never saw it catch the bug
-
-Test-first forces you to see the test fail, proving it actually tests something.
-
-**"I already manually tested all the edge cases"**
-
-Manual testing is ad-hoc. You think you tested everything but:
-- No record of what you tested
-- Can't re-run when code changes
-- Easy to forget cases under pressure
-- "It worked when I tried it" ≠ comprehensive
-
-Automated tests are systematic. They run the same way every time.
-
-**"Deleting X hours of work is wasteful"**
-
-Sunk cost fallacy. The time is already gone. Your choice now:
-- Delete and rewrite with TDD (X more hours, high confidence)
-- Keep it and add tests after (30 min, low confidence, likely bugs)
-
-The "waste" is keeping code you can't trust. Working code without real tests is technical debt.
+## Why order matters
 
-**"TDD is dogmatic, being pragmatic means adapting"**
+A failing test can expose a misunderstood requirement before implementation. A test written after a fix can still be valuable, but its sensitivity to the original defect needs evidence. Neither timing nor coverage percentage proves the assertion is meaningful.
 
-TDD IS pragmatic:
-- Finds bugs before commit (faster than debugging after)
-- Prevents regressions (tests catch breaks immediately)
-- Documents behavior (tests show how to use code)
-- Enables refactoring (change freely, tests catch breaks)
-
-"Pragmatic" shortcuts = debugging in production = slower.
-
-**"Tests after achieve the same goals - it's spirit not ritual"**
-
-No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"
-
-Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.
-
-Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).
-
-30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.
-
-## Common Rationalizations
-
-| Excuse | Reality |
-|--------|---------|
-| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
-| "I'll test after" | Tests passing immediately prove nothing. |
-| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
-| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
-| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
-| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
-| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
-| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
-| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
-| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
-| "Existing code has no tests" | You're improving it. Add tests for existing code. |
-
-## Red Flags - STOP and Start Over
-
-- Code before test
-- Test after implementation
-- Test passes immediately
-- Can't explain why test failed
-- Tests added "later"
-- Rationalizing "just this once"
-- "I already manually tested it"
-- "Tests after achieve the same purpose"
-- "It's about spirit not ritual"
-- "Keep as reference" or "adapt existing code"
-- "Already spent X hours, deleting is wasteful"
-- "TDD is dogmatic, I'm being pragmatic"
-- "This is different because..."
-
-**All of these mean: Delete code. Start over with TDD.**
+If a failure is caused by a missing import, unavailable service or bad fixture, repair that setup before interpreting the result. Use real boundaries where practical; a mock is useful when it isolates an external dependency while preserving the contract under test.
 
 ## Example: Bug Fix
 
@@ -330,8 +230,8 @@ Extract validation for multiple fields if needed.
 
 Before marking work complete:
 
-- [ ] Every new function/method has a test
-- [ ] Watched each test fail before implementing
+- [ ] Changed behavior and consequential failure paths have appropriate tests
+- [ ] Regression sensitivity is demonstrated; timing of the test is reported honestly
 - [ ] Each test failed for expected reason (feature missing, not typo)
 - [ ] Wrote minimal code to pass each test
 - [ ] All tests pass
@@ -339,7 +239,7 @@ Before marking work complete:
 - [ ] Tests use real code (mocks only if unavoidable)
 - [ ] Edge cases and errors covered
 
-Can't check all boxes? You skipped TDD. Start over.
+Record any unmet check and its consequence. Do not erase work or claim an unobserved failure to complete a checklist.
 
 ## When Stuck
 
@@ -354,7 +254,7 @@ Can't check all boxes? You skipped TDD. Start over.
 
 Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
 
-Never fix bugs without a test.
+Prefer a reproducible regression for a bug fix; use another explicit verifier when a test cannot reasonably exercise the failure.
 
 ## Testing Anti-Patterns
 
@@ -363,16 +263,13 @@ When adding mocks or test utilities, read @testing-anti-patterns.md to avoid com
 - Adding test-only methods to production classes
 - Mocking without understanding dependencies
 
-## Final Rule
+## Inputs and expected result
 
-```
-Production code → test exists and failed first
-Otherwise → not TDD
-```
-
-No exceptions without your human partner's permission.
+You need the user-visible requirement, the current implementation, a known runner and a controlled fixture. In the empty-email example, the failure must be “missing validation”, not a network outage. Expected: the regression fails on the defective behavior and passes after the smallest repair, while existing valid submissions still work.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
-- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
-- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+- A passing unit test does not prove browser, packaged-runtime or provider integration behavior.
+- Retry examples assume retry-safe operations; production retries need explicit idempotency, cancellation and retryable-error policy.
+- Test-first order does not prevent incorrect requirements or over-mocking. Inspect assertions and real boundaries.
+- Preserve unrelated changes and use the project’s existing test commands rather than assuming every `npm test` accepts the same arguments.

package/bundled-skills/test-driven-development/testing-anti-patterns.md

@@ -8,7 +8,7 @@ Tests must verify real behavior, not mock behavior. Mocks are a means to isolate
 
 **Core principle:** Test what the code does, not what the mocks do.
 
-**Following strict TDD prevents these anti-patterns.**
+Test-first work can reveal these mistakes, but test order alone does not prevent them.
 
 ## The Iron Laws
 
@@ -120,7 +120,7 @@ BEFORE adding any method to production class:
 **The violation:**
 ```typescript
 // ❌ BAD: Mock breaks test logic
-test('detects duplicate server', () => {
+test('detects duplicate server', async () => {
   // Mock prevents config write that test depends on!
   vi.mock('ToolCatalog', () => ({
     discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
@@ -139,12 +139,12 @@ test('detects duplicate server', () => {
 **The fix:**
 ```typescript
 // ✅ GOOD: Mock at correct level
-test('detects duplicate server', () => {
+test('detects duplicate server', async () => {
   // Mock the slow part, preserve behavior test needs
   vi.mock('MCPServerManager'); // Just mock slow server startup
 
   await addServer(config);  // Config written
-  await addServer(config);  // Duplicate detected ✓
+  await expect(addServer(config)).rejects.toThrow(/duplicate/i);
 });
 ```
 
@@ -260,7 +260,7 @@ TDD cycle:
 
 **Consider:** Integration tests with real components often simpler than complex mocks
 
-## TDD Prevents These Anti-Patterns
+## How test-first work can reveal these anti-patterns
 
 **Why TDD helps:**
 1. **Write test first** → Forces you to think about what you're actually testing
@@ -268,7 +268,7 @@ TDD cycle:
 3. **Minimal implementation** → No test-only methods creep in
 4. **Real dependencies** → You see what the test actually needs before mocking
 
-**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
+An assertion on a mock call can be valid when the call is the contract, such as sending exactly one notification. Pair it with appropriate integration coverage; asserting only that a mocked component exists rarely verifies the user flow.
 
 ## Quick Reference