Skip to main content
skill CX Codex

mocktail — Claude Code skill: mocking and setup

Guidance for using Mocktail in Dart and Flutter tests: configure stubs, inspect interactions, and decide when a mock, fake, or real object fits.

MIT ★ 674 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add evanca/flutter-ai-rules
/plugin install flutter-ai-skills@flutter-ai-rules
Open on GitHub

What mocktail does

The skill lays out when to keep a real object, write a small fake, or use a mock to inspect calls and arguments. It covers setting return values and errors, capturing arguments, and checking whether a method ran. Async methods use thenAnswer.

Examples show Mock and Fake classes, when stubs, and verify checks. Custom types passed to any(), captureAny(), or captureThat() need a fallback registered first. That requirement matters for non-nullable custom types; when interaction checks are unnecessary, the guidance favors a fake or real object over a mock.

What it helps with

  • choose a mock, fake, or real object for a test
  • stub a method to return a value or throw an error
  • check how often a method ran and which arguments it received
  • capture method arguments for later assertions
  • register fallback values for custom argument types

Example prompts for the agent

  • Help me write a Dart test with Mocktail and check how often fetchData runs.
  • Stub the async fetchData method to return a test result.
  • Show me how to capture the argument passed to process and assert its value.

How to install mocktail

1Plugin marketplace

/plugin marketplace add evanca/flutter-ai-rules
/plugin install flutter-ai-skills@flutter-ai-rules

This installs the whole flutter-ai-skills plugin with all its skills

2Skills CLI (Vercel)

npx skills add evanca/flutter-ai-rules --skill mocktail -a claude-code

3Manually: put the files in place

~/.claude/skills/mocktail/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mocktail/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mocktail

How do I install mocktail in Claude Code?

Add the marketplace with /plugin marketplace add evanca/flutter-ai-rules, then install the skill with /plugin install flutter-ai-skills@flutter-ai-rules.

What does the mocktail skill do?

It guides you through stubbing methods and checking interactions in Dart and Flutter tests. It also explains when a mock, fake, or real object is the right choice.

When should I register a Mocktail fallback value?

Register it before matching a custom type with any(), captureAny(), or captureThat(). The skill shows registration in setUpAll or at the start of a test.

Source text

SKILL.md · MIT
---
name: mocktail
description: "Use when creating mocks, stubbing methods, verifying interactions, registering fallback values, or choosing between mocks, fakes, and real objects (Mocktail)."
license: MIT
---

# Mocktail Skill

This skill defines how to correctly use the `mocktail` package for mocking in Dart and Flutter tests.

---

## 1. Mock vs. Fake vs. Real Object

| Use | When |
|---|---|
| **Real object** | Prefer over mocks when practical. |
| **Fake** (`extends Fake`) | Lightweight custom implementation; override only the methods you need. Prefer over mocks when you don't need interaction verification. |
| **Mock** (`extends Mock`) | Only when you need to **verify interactions** (call counts, arguments) or stub dynamic responses. |

- Never add `@override` methods or implementations to a class extending `Mock`.
- Only use mocks if your test has `verify` assertions; otherwise prefer real or fake objects.

---

## 2. Creating Mocks

```dart
class MockMyService extends Mock implements MyService {}
class FakeMyEvent extends Fake implements MyEvent {}
```

No code generation required — unlike Mockito, Mocktail uses `noSuchMethod` at runtime.

---

## 3. Registering Fallback Values

Register fallback values **before** using custom types with argument matchers. Do this in `setUpAll` or at the top of your test:

```dart
setUpAll(() {
  registerFallbackValue(FakeMyEvent());
});
```

- Required for non-nullable custom types used with `any()`, `captureAny()`, or `captureThat()`.
- Register fallback values for **any** custom type used with argument matchers.

---

## 4. Stubbing

```dart
final mock = MockMyService();

// Return a value
when(() => mock.fetchData()).thenReturn('result');

// Throw an error
when(() => mock.fetchData()).thenThrow(Exception('error'));

// Dynamic/async response
when(() => mock.fetchData()).thenAnswer((_) async => 'result');

// Future<void>
when(() => mock.doWork()).thenAnswer((_) async {});
```

- Always stub async methods (returning `Future` or `Future<void>`) with `thenAnswer`.
- Stub every method you expect to be called, even if it's not the focus of your test.

---

## 5. Named Parameters

Always include **all named parameters** in both `when` and `verify` calls. Use `any(named: 'paramName')` for those you don't care about:

```dart
when(() => mock.fetch(
  id: any(named: 'id'),
  headers: any(named: 'headers'),
)).thenReturn(response);
```

- If a method has default values for named parameters, Mocktail still expects them all to be matched.

---

## 6. Verification

```dart
verify(() => mock.fetchData());             // called at least once
verifyNever(() => mock.fetchData());        // never called
verify(() => mock.fetchData()).called(2);   // called exactly twice
```

---

## 7. Argument Matchers

```dart
// Any positional argument
when(() => mock.process(any())).thenReturn(true);

// Capture arguments for later assertions
final captured = verify(() => mock.process(captureAny())).captured;
print(captured.last);
```

- Use `any()` for positional parameters when you don't care about the exact value.
- Use `captureThat()` for conditional capturing.
- When matching string output, be aware of what `.toString()` returns for the type.

---

## References

- [Mocktail GitHub Repository](https://github.com/felangel/mocktail)

© Ivanna Kaceviča · MIT · evanca/flutter-ai-rules

Similar skills

SKILL.md skills catalog →

From the same set39

The whole set →
flutter_errors This rule connects common Flutter errors to likely layout or state-management causes. Use it when a widget tree fails with overflow, sizing, or build-phase issues. CX Codex +1 ★ 674repo stars code_review The code_review rule for Claude Code sets a review process for changes before merging. It checks branches, files, code, tests, and the PR/MR description. CX Codex +1 ★ 674repo stars flutter-errors flutter-errors is a Claude Code skill that helps diagnose Flutter layout and runtime errors. It activates for RenderFlex overflow, scroll issues, and setState calls during build. CX Codex +1 ★ 674repo stars flutter-change-notifier flutter-change-notifier — a skill that teaches the agent to use ChangeNotifier and provider for Flutter state management: models, providers, Consumer, rebuild optimization. CX Codex +1 ★ 674repo stars provider Guides agents on architecting Flutter state with the provider package, keeping rebuilds minimal and dependencies reactive. CX Codex +1 ★ 674repo stars mockito mockito is a Claude Code skill for Dart and Flutter tests that guides mock generation, stubbing, and interaction checks. It activates for Mockito testing tasks. CX Codex +1 ★ 674repo stars developing-genkit-dart developing-genkit-dart — a skill for building AI agents with Genkit Dart that tells the agent when to pull in reference docs for the core framework and its plugins. CX Codex +1 ★ 674repo stars firebase-storage firebase-storage is a skill with guidelines for Firebase Cloud Storage in Flutter apps, covering file uploads, downloads, metadata changes, and storage error handling. CX Codex +1 ★ 674repo stars

Project sponsors

Companies that keep this analytics open