### Basic TestBot Setup and Command Simulation

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

This snippet demonstrates the fundamental setup for testing a Mineral bot using TestBot. It shows how to create a TestBot instance, register a listener, simulate a command, and assert on the interaction reply.

```dart
import 'package:mineral_test/mineral_test.dart';
import 'package:test/test.dart';

void main() {
  late TestBot bot;

  setUp(() async => bot = await TestBot.create());
  tearDown(() => bot.dispose());

  test('replies with pong', () async {
    bot.events.register(PingListener());

    await bot.simulateCommand('ping', invokedBy: UserBuilder().build());

    expect(
      bot.actions.interactionReplies,
      contains(isInteractionReplied(content: 'pong')),
    );
  });
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/mineral-dart/mineral/blob/main/README.md

Installs all project dependencies using Dart workspaces. This command should be run from the root of the project.

```bash
dart pub get
```

--------------------------------

### Install Mineral Cache

Source: https://github.com/mineral-dart/mineral/blob/main/packages/cache/README.md

Add the mineral_cache dependency to your pubspec.yaml file and run dart pub get to install the package.

```yaml
dependencies:
  mineral_cache: ^1.2.0
```

--------------------------------

### Handle Server Member Add Event

Source: https://github.com/mineral-dart/mineral/blob/main/packages/core/README.md

Implement the `ServerMemberAddEvent` to react when a new member joins the server. This example sends a welcome message to the system channel.

```dart
final class OnMemberJoin extends ServerMemberAddEvent {
  @override
  Future<void> handle(Member member, Server server) async {
    final channel = await server.channels.resolveSystemChannel();
    await channel?.send(MessageBuilder.text('Welcome, ${member.username}!'));
  }
}
```

--------------------------------

### Configure Memory Cache with Custom TTL Policy

Source: https://github.com/mineral-dart/mineral/blob/main/packages/cache/README.md

Customize the runtime behavior of the MemoryProvider by providing a CacheConfig. This example sets a specific TTL for entries starting with 'users/'.

```dart
.setCache(MemoryProvider.new, config: CacheConfig.defaults())   // default
.setCache(MemoryProvider.new, config: CacheConfig.legacy())     // pre-v5
.setCache(MemoryProvider.new, config: CacheConfig(
  ttlPolicy: CacheTtlPolicy.defaults().override({
    'users/': const Duration(minutes: 15),
  }),
  sweeperInterval: const Duration(seconds: 30),
))
```

--------------------------------

### Initialize Client with In-Memory Cache

Source: https://github.com/mineral-dart/mineral/blob/main/packages/cache/README.md

Initialize the Mineral client, setting the cache provider to MemoryProvider. This is a basic setup for in-memory caching.

```dart
final client = ClientBuilder()
  .setIntent(Intent.allNonPrivileged)
  .setCache(MemoryProvider.new)
  .build();
```

--------------------------------

### Define a Command Listener

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

This example shows how to create a custom listener for slash commands. It extends `OnCommandListener` and defines the `command` getter and the `handle` method to process the command invocation.

```dart
final class PingListener extends OnCommandListener {
  @override
  String get command => 'ping';

  @override
  Future<void> handle(CommandInvocation invocation) async {
    await TestInteractionResponder.reply(
      interactionId: invocation.interactionId,
      token: invocation.token,
      content: 'pong',
    );
  }
}
```

--------------------------------

### Initialize Mineral Client

Source: https://github.com/mineral-dart/mineral/blob/main/packages/core/README.md

Set up the Discord client with intents, register providers, and initialize the client.

```dart
// main.dart
void main() async {
  final client = ClientBuilder()
    .setIntent(Intent.allNonPrivileged)
    .registerProvider(MyProvider.new)
    .build();

  await client.init();
}
```

--------------------------------

### Initialize Bot with Providers

Source: https://github.com/mineral-dart/mineral/blob/main/README.md

Sets up the Discord client with necessary intents and registers custom providers for bot functionality. Ensure intents are correctly configured for your bot's needs.

```dart
void main() async {
  final client = ClientBuilder()
    .setIntent(Intent.allNonPrivileged)
    .registerProvider(WelcomeProvider.new)
    .registerProvider(FeedbackProvider.new)
    .build();

  await client.init();
}
```

--------------------------------

### Create a Basic Provider

Source: https://github.com/mineral-dart/mineral/blob/main/packages/core/README.md

Define a provider class that extends `Provider` and registers commands and events.

```dart
// my_provider.dart
final class MyProvider extends Provider {
  final Client _client;

  MyProvider(this._client) {
    _client
      ..register<MyCommand>(MyCommand.new)
      ..register<OnMemberJoin>(OnMemberJoin.new);
  }
}
```

--------------------------------

### Simulate Modal Submission

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Shows how to simulate a modal submission using `bot.simulateModalSubmit`. Include the custom ID of the modal, the submitting user, and the submitted fields.

```dart
await bot.simulateModalSubmit('feedback',
    submittedBy: user, fields: {'comment': 'nice'});
```

--------------------------------

### Publish Core Package

Source: https://github.com/mineral-dart/mineral/blob/main/README.md

Publishes the core 'mineral' package to pub.dev by creating and pushing a git tag. The tag format should follow the pattern 'core-vX.Y.Z'.

```bash
git tag core-v4.3.0 && git push origin core-v4.3.0
```

--------------------------------

### Create a Slash Command with Options

Source: https://github.com/mineral-dart/mineral/blob/main/README.md

Defines a slash command named 'say' that accepts a 'message' option and replies with the provided text. Ensure the command is registered with the bot.

```dart
final class SayCommand implements CommandDeclaration {
  Future<void> handle(ServerCommandContext ctx, CommandOptions options) async {
    final message = options.require<String>('message');
    await ctx.interaction.reply(builder: MessageBuilder.text(message));
  }

  @override
  CommandDeclarationBuilder build() {
    return CommandDeclarationBuilder()
      ..setName('say')
      ..setDescription('Repeat a message')
      ..addOption(Option.string(name: 'message', description: 'Text to repeat', required: true))
      ..setHandle(handle);
  }
}
```

--------------------------------

### Simulate Member Join Event

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

This snippet demonstrates simulating a member join event using `bot.simulateMemberJoin`. You need to provide the member and the guild they joined.

```dart
await bot.simulateMemberJoin(member: member, guild: guild);
```

--------------------------------

### Simulate Command Invocation

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

This snippet shows how to simulate a command invocation using `bot.simulateCommand`. You can provide command name, options, and the user who invoked it.

```dart
await bot.simulateCommand('echo',
    options: {'message': 'hi'}, invokedBy: user);
```

--------------------------------

### Construct User Payload with UserBuilder

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Demonstrates using UserBuilder to fluently construct a user payload for testing. You can set properties like username and specify if the user is a bot.

```dart
final user = UserBuilder()
  .withUsername('alice')
  .asBot()
  .build();
```

--------------------------------

### Construct Member Payload with MemberBuilder

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Demonstrates using MemberBuilder to create a member payload. This allows associating a user with a guild and assigning them roles.

```dart
final member = MemberBuilder()
  .ofGuild(guild)
  .withUser(user)
  .withRole(role)
  .build();
```

--------------------------------

### Simulate Button Click

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Demonstrates simulating a button click event using `bot.simulateButton`. Provide the custom ID of the button and the user who clicked it.

```dart
await bot.simulateButton('vote_yes', clickedBy: user);
```

--------------------------------

### Simulate Command Invocation and Expect Reply

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Simulate a command being invoked by a user and expect a specific reply content.

```dart
await bot.whenCommand('ping')
    .invokedBy(user)
    .expectReply(content: 'pong');
```

--------------------------------

### Analyze a Specific Package

Source: https://github.com/mineral-dart/mineral/blob/main/README.md

Performs static analysis on a specified package to check for errors and style issues. Adjust the package path as needed.

```bash
dart analyze packages/core
```

```bash
dart analyze packages/cache
```

--------------------------------

### Simulate Member Join and Expect Role Assignment

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Simulate a member joining a guild and expect a specific role to be assigned.

```dart
await bot.whenMemberJoins(guild)
    .forMember(member)
    .expectRoleAssigned(roleId: memberRole.id);
```

--------------------------------

### Publish Cache Package

Source: https://github.com/mineral-dart/mineral/blob/main/README.md

Publishes the 'mineral_cache' package to pub.dev. This involves creating and pushing a git tag, typically in the format 'cache-vX.Y.Z'.

```bash
git tag cache-v1.3.0 && git push origin cache-v1.3.0
```

--------------------------------

### Simulate Button Click and Expect Modal

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Simulate a button click by a user and expect a modal with a specific custom ID.

```dart
await bot.whenButton('vote_yes')
    .clickedBy(user)
    .expectModal(customId: 'feedback');
```

--------------------------------

### Simulate Modal Submit and Expect Reply

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Simulate a modal submission with specific field values by a user and expect a reply containing certain text.

```dart
await bot.whenModalSubmit('feedback')
    .withFields({'comment': 'great'})
    .submittedBy(user)
    .expectReply(content: contains('thanks'));
```

--------------------------------

### Construct Channel Payload with ChannelBuilder

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Illustrates using ChannelBuilder to create a channel payload. You can specify the channel's name and associate it with a guild.

```dart
final channel = ChannelBuilder()
  .ofGuild(guild)
  .withName('general')
  .build();
```

--------------------------------

### Construct Role Payload with RoleBuilder

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Shows how to use RoleBuilder to create a role payload. You can specify the role's name and associate it with a guild.

```dart
final role = RoleBuilder()
  .withName('Member')
  .ofGuild(guild)
  .build();
```

--------------------------------

### Declare a Slash Command

Source: https://github.com/mineral-dart/mineral/blob/main/packages/core/README.md

Define a slash command class that implements `CommandDeclaration`. It includes setting the name, description, options, and the handler function.

```dart
final class MyCommand implements CommandDeclaration {
  Future<void> handle(ServerCommandContext ctx, CommandOptions options) async {
    final target = options.require<String>('message');
    await ctx.interaction.reply(builder: MessageBuilder.text(target));
  }

  @override
  CommandDeclarationBuilder build() {
    return CommandDeclarationBuilder()
      ..setName('say')
      ..setDescription('Repeat a message')
      ..addOption(Option.string(name: 'message', description: 'Text to repeat', required: true))
      ..setHandle(handle);
  }
}
```

--------------------------------

### Run Tests for a Specific Package

Source: https://github.com/mineral-dart/mineral/blob/main/README.md

Executes tests for a particular package within the Dart workspace. Replace 'packages/core' or 'packages/cache' with the desired package path.

```bash
dart test packages/core
```

```bash
dart test packages/cache
```

--------------------------------

### Construct Guild Payload with GuildBuilder

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Illustrates using GuildBuilder to create a guild payload. The builder allows setting the guild's name and will generate a unique ID if none is provided.

```dart
final guild = GuildBuilder()
  .withName('Mineral HQ')
  .build();
```

--------------------------------

### Define a Provider Class

Source: https://github.com/mineral-dart/mineral/blob/main/README.md

A provider class groups related commands, events, and components. It uses dependency injection to access the client and registers event handlers.

```dart
final class WelcomeProvider extends Provider {
  final Client _client;

  WelcomeProvider(this._client) {
    _client
      ..register<OnMemberJoin>(OnMemberJoin.new)
      ..register<FeedbackButton>(FeedbackButton.new);
  }
}
```

--------------------------------

### Add Mineral Dependency

Source: https://github.com/mineral-dart/mineral/blob/main/packages/core/README.md

Add the Mineral package to your project's dependencies.

```yaml
dependencies:
  mineral: ^4.2.0
```

--------------------------------

### Add mineral_test to dev_dependencies

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

To use mineral_test, add it to your project's dev_dependencies in the pubspec.yaml file. Ensure you also have the 'test' package.

```yaml
dev_dependencies:
  mineral_test: ^0.1.0
  test: ^1.28.0
```

--------------------------------

### Implement Global State

Source: https://github.com/mineral-dart/mineral/blob/main/packages/core/README.md

Define a contract for global state and a concrete implementation. Global state can be accessed from any handler using the `State` mixin.

```dart
abstract interface class CounterContract implements GlobalState<int> {
  void increment();
}

final class Counter implements CounterContract {
  int _count = 0;

  @override
  int get state => _count;

  @override
  void increment() => _count++;
}

// Register
client.register<CounterContract>(Counter.new);

// Use (in any handler with the State mixin)
state.read<CounterContract>().increment();
```

--------------------------------

### Seed Data Store

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Seed the in-memory data store with initial guild, role, and member data before running handlers.

```dart
bot.dataStore.seed(
  guilds: [guild],
  roles: [memberRole],
  members: [member],
);

await bot.simulateMemberJoin(member: member, guild: guild);

final updated = bot.dataStore.member(member.id, in_: guild);
expect(updated.roles, contains(memberRole));
```

--------------------------------

### Revert to Legacy Memory Cache Behavior

Source: https://github.com/mineral-dart/mineral/blob/main/packages/cache/README.md

Opt out of the new TTL behavior and preserve the pre-v5 cache behavior where entries live forever and automatic invalidation is disabled.

```dart
.setCache(MemoryProvider.new, config: CacheConfig.legacy())
```

--------------------------------

### Modal Shown Matcher

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Assert that a modal was shown with a specific custom ID and title.

```dart
expect(bot.actions.modals,
    contains(isModalShown(customId: 'feedback', title: 'Tell us more')));
```

--------------------------------

### Handle Button Click Event

Source: https://github.com/mineral-dart/mineral/blob/main/packages/core/README.md

Implement the `ServerButtonClickEvent` to handle interactions with buttons. The `customId` property links the button to this handler.

```dart
final class MyButton extends ServerButtonClickEvent {
  @override
  String? get customId => 'my_button';

  @override
  Future<void> handle(ServerButtonContext ctx) async {
    await ctx.interaction.reply(builder: MessageBuilder.text('Clicked!'));
  }
}
```

--------------------------------

### Interaction Replied Matcher

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Assert that an interaction reply was sent with specific content and ephemeral status.

```dart
expect(bot.actions.interactionReplies,
    contains(isInteractionReplied(content: 'pong', ephemeral: false)));
```

--------------------------------

### Handle Button Interaction

Source: https://github.com/mineral-dart/mineral/blob/main/README.md

Handles a button click event based on its custom ID. This snippet shows how to bind a handler to a specific button and reply to the interaction.

```dart
final class FeedbackButton extends ServerButtonClickEvent {
  @override
  String? get customId => 'open_feedback';

  @override
  Future<void> handle(ServerButtonContext ctx) async {
    await ctx.interaction.reply(
      builder: MessageBuilder.text('Thanks for your feedback!'),
    );
  }
}
```

--------------------------------

### Role Assigned Matcher

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Assert that a role was assigned to a specific member.

```dart
expect(bot.actions.roleAssignments,
    contains(isRoleAssigned(memberId: member.id, roleId: role.id)));
```

--------------------------------

### Member Banned Matcher

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Assert that a member was banned with a specific reason.

```dart
expect(bot.actions.bans,
    contains(isMemberBanned(memberId: target.id, reason: 'spam')));
```

--------------------------------

### Message Content Matcher

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Assert that a sent message's content contains a specific substring.

```dart
expect(bot.actions.sentMessages,
    contains(isMessageSent(content: contains('hello'))));
```

--------------------------------

### Message Sent Matcher

Source: https://github.com/mineral-dart/mineral/blob/main/packages/test/README.md

Assert that a message was sent to a specific channel with exact content.

```dart
expect(bot.actions.sentMessages,
    contains(isMessageSent(channelId: 'general', content: 'hello')));
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.