Version: 4.x

Expect

When testing functionalities with an bot, expect will let you define what a bot should do given a command passed to it. All tests current available in this version are listed bellow:

Message tests

Role tests

note

All examples below are only to illustrate the functions called after expect. These examples are not used exactly to show they are described in a real use case.

Reference

`expect(string | number | Function, customChannelId)`

Expect is a function that receives a command as an argument. The same argument that you would send to Discord to invoke some action from your bot. As there is a prefix witch can be passed in the config file, there is no need to pass that prefix in the expect function.

The expected function receives by default a string, but it can the value can be of any type. This type will be resolved for a string value that will be used as the command.

I.E:

Supposing that there is a bot with prefix ! and that bot has a command called createAGuild, you can use expect like the example below:

expect("createAGuild");

Is is also possible to pass a function that returns the command:

expect(1); // Valid
expect(() => "createGuild"); // Valid
expect(() => Promise.resolve("createGuild")); // Valid

This function returns several other functions to define what Corde should check after that command be invoke.

expect also has a second optional parameter: channelId. It allows corde to send the command message to a custom channel.

expect("ping", "831288248180408371");

This expects will send the command ping in channel 831288248180408371.

note

If for some reason you what to pass the bot prefix in expect, do not use the config variable prefix.

`inChannel(channelId)`

Use inChannel to define a custom channel to corde validate a test. the default value is defiend in config.channelId When using inChannel, only message tests will be available.

I.E:

group("inChannel", () => {
  const message = {
    channelId: "831288248180408371",
    content: "hello2",
  };

  test("testing message in a outside channel", () => {
    expect("sendInChannel").inChannel(message.channelId).toReturn(message.content);
  });
});

The example above will check if the command sendInChannel sent the message hello2 in the text channel of id 831288248180408371.

`inGuild(guildId)`

Use inGuild to define a custom guild to corde validate a test. the default value is defiend in config.guildId When using inGuild, only role tests will be available.

I.E:

group("inGuild", () => {
  const roleGuild = {
    guildId: "522581719568744468",
    newName: "newRole",
    id: "829873348309155851",
  };

  test("testing role in outside default guild", () => {
    expect("renameOtherRole")
      .inGuild(roleGuild.guildId)
      .toRenameRole(roleGuild.newName, roleGuild.id);
  });
});

The example above will check if the command renameOtherRole renamed the role located of guild 522581719568744468 and id 829873348309155851 to newRole.

`not`

Use not to deny some test after this keyword. It can be used to check if an operation made by a bot command is anything but not something.

I.E:

group("not", () => {
  const notExpectedValue = 1;

  test("command hello should not return 1", () => {
    expect("hello").not.toReturn(notExpectedValue);
  });
});

`toHaveResult(expectReport)`

Use toHaveResult if you want to check if the command did many operations. This function makes use of reports created by all test functions that are called from expect as a property.

I.E:

group("toHaveResult", () => {
  const expectedMessage = {
    content: "Hello2",
    channelId: "831288249254674453",
  };

  test("testing multiple tests", () => {
    expect("sendMultipleMessage").toHaveResult(
      expect.toReturn("Hello"),
      expect.inChannel(expectedMessage.channelId).toReturn(expectedMessage.content),
    );
  });
});

In the example above, corde will check if the command sendMultipleMessage sent the message Hello in the channel defined in configs, and the message Hello2 in a channel of id 831288249254674453.

All test functions are available from the property expect.

`toAddReaction(emojis, messageIdentifier)`

type of emojis:

string[] | IEmoji[] | (string | IEmoji)[]

type of messageIdentifier:

string | MessageIdentifier;

Use toAddReaction to check if the bot added a reaction or a list of reactions to the last message sent by someone who is not a bot.

group("toAddReaction", () => {
  const messageId = "15198241251";

  test("testing multiple reactions", () => {
    // This will check if the emoji 😄 was added in the last message sent
    expect("addReactions").toAddReaction(["😄"]);

    expect("addReactions").toAddReaction(["😄"], messageId);
    expect("addReactions").toAddReaction([{ name: "🍊" }], messageId);
    // Customized Reaction
    expect("addReactions").toAddReaction([{ id: "121512312" }], messageId);

    expect("addReactions").toAddReaction([{ id: "121512312" }], { id: messageId });

    // It's more assertive to find the message by it's id, but is possible to find using the content
    expect("addReactions").toAddReaction([{ id: "121512312" }], { content: "banana" });
  });
});

note

This example is only to illustrate how this test can be used, not a real case usage of this. We also will allow adding the id of a message, in this test in the future.

`toEditMessage(newContent, messageIdentifier)`

type of newContent

string | number | boolean | IMessageEmbed

type of messageIdentifier

MessageEditedIdentifier | string

Use toEditMessage to check if a bot command edited a sent message.

group("toEditMessage", () => {
  test("testing multiple editions", () => {
    // message: Message; -> content = "value";
    expect(`editMessage ${message.id}`).toEditMessage("new value", { id: message.id });
    expect(`editMessage ${message.id}`).toEditMessage(123, { id: message.id });
    // Don't know why someone would send a boolean message but its converted to "true"
    expect(`editMessage ${message.id}`).toEditMessage(true, { id: message.id });
    // Embed message
    expect(`editMessage ${message.id}`).toEditMessage(
      {
        color: 3447003,
        description: "description of this message",
        fields: [
          {
            name: "field 1",
            value: "1",
          },
        ],
        url: "wwww.google.com.br",
        title: "title message",
        timestamp: timeNow,
      },
      { id: message.id },
    );
  });
});

`toPin(string | MessageIdentifier)`

use toPin to check if a bot command pinned a message in the channel.

Example pinned message

group("toPing", () => {
  const message = {
    id: "241212917212",
  };

  test("should pin the message", () => {
    expect(`ping ${message.id}`).toPin(message.id);
  });
});

`toRemoveReaction(emojis, messageIdentifier)`

type of emojis:

string[] | IEmoji[] | (string | IEmoji)[]

type of messageIdentifier:

string | MessageIdentifier;

Use toRemoveReaction to check if a reaction or a list of reactions were removed after a command call.

group("toRemoveReaction", () => {
  const messageId = "15198241251";

  test("testing reactions remotion", () => {
    // This will check if the emoji 😄 was removed in the last message sent
    expect("removeReactions").toRemoveReaction(["😄"]);

    expect("removeReactions").toRemoveReaction(["😄"], messageId);
    expect("removeReactions").toRemoveReaction([{ name: "🍊" }], messageId);
    // Customized Reaction
    expect("removeReactions").toRemoveReaction([{ id: "121512312" }], messageId);

    expect("removeReactions").toRemoveReaction([{ id: "121512312" }], { id: messageId });

    // It's more assertive to find the message by it's id, but is possible to find using the content
    expect("removeReactions").toRemoveReaction([{ id: "121512312" }], { content: "banana" });
  });
});

`toReturn(string | boolean | number | messageEmbedSimple)`

Use toReturn to check if the bot send a primitive message value or an EmbedMessage after the call of an command passed in expect.

I.E:

Given a bot who has a command called hi and return Hello!!, you can test it with:

group("toReturn", () => {
  const expectedReturn = "Hello!!";

  test("command hi should return Hello!", () => {
    expect("hi").toReturn(expectedReturn);
  });
});

group("toReturn", () => {
  const expectedReturn = "Hello!!";

  test("command hi should return embed", () => {
    expect("hi").toReturn({
      color: 3447003,
      description: "description of this message",
      fields: [
        {
          name: "field 1",
          value: "1",
        },
      ],
      url: "wwww.google.com.br",
      title: "title message",
      timestamp: timeNow,
    });
  });
});

`toUnpin(string | MessageIdentifier)`

Use toUnpin to check if a bot command unpinned a message.

group("toUnpin", () => {
  const message = {
    id: "241212917212",
  };

  test("should unpin the message", () => {
    expect(`ping ${message.id}`).toUnpin(message.id);
  });
});

`toDeleteRole(string | RoleIdentifier)`

Use toDeleteRole to check if a bot command deleted a role in guild defined in guildId.

group("toDeleteRole", () => {
  const role = {
    id: "1231249817231",
    name: "hc",
  };

  test("should delete a role", () => {
    expect(`deleteRole ${role.id}`).toDelete(role.id);
    expect(`deleteRole ${role.id}`).toDelete({ id: role.id });
    expect(`deleteRole ${role.id}`).toDelete({ name: role.name });
  });
});

`toMessageContentContains(value)`

Use toMessageContentContains to check if a text message sent by a bot contains a determined value. This is useful if you are not sure about the full content of a message. For example, if the message contains a date, use these functions may help.

group("toMessageContentContains", () => {
  const partialMessage = "pon";
  test("bot message should contains 'pong'", () => {
    expect("ping").toMessageContentContains(partialMessage);
  });
});

`toEmbedMatch(embedMessage)`

Use toEmbedMatch to check if an embed message sent by the bot contains some properties. It is useful when you are not sure about how each property of the embed message will be filled with.

group("toEmbedMatch", () => {
  const partialEmbedMessage = {
    title: "embed title",
    description: "embed description",
  };
  test("bot embed message title and description properties", () => {
    expect("embed").toEmbedMatch(partialEmbedMessage);
  });
});

`toRenameRole(string, string | RoleIdentifier)`

Use toRenameRole to check if a bot command renamed a role.

group("toRenameRole", () => {
  const role = {
    id: "1231212312",
    name: "support",
  };

  test("should rename role", () => {
    // role.name = hight-master
    expect(`renameRole ${role.id}`).toRenameRole("dm-hight-master", role.id);
    expect(`renameRole ${role.id}`).toRenameRole("dm-hight-master", { id: role.id });
    expect(`renameRole ${role.id}`).toRenameRole("dm-hight-master", { name: role.name });
  });
});

`toSetRoleColor(ColorResolvable | Colors, string | RoleIdentifier)`

Use toSetRoleColor to check if a bot command sets a new color to a role.

Example pinned message

group("toSetRoleColor", () => {
  const role = {
    id: "321162516521",
    name: "offlane",
  };

  test("should set role color", () => {
    // role.name = hight-master
    expect(`setColor ${role.id}`).toSetRoleColor("GREEN", role.id);
    expect(`setColor ${role.id}`).toSetRoleColor(Colors.GREEN, role.id);
    expect(`setColor ${role.id}`).toSetRoleColor("GREEN", { id: role.id });
    expect(`setColor ${role.id}`).toSetRoleColor(Colors.GREEN, { id: role.id });
    expect(`setColor ${role.id}`).toSetRoleColor("GREEN", { name: role.name });
  });
});

`toSetRoleHoist(boolean, string | RoleIdentifier)`

Use toSetRoleHoist to check if a bot command sets or not a role as a hoist.

Example mentionable role

In a hoisted configuration, the role hierarchy is visibly clear to server members; roles are sorted and displayed based on which role is higher in the role management menu. However, in a standard configuration, users are sorted alphabetically, meaning someone with the highest roll will be sorted wherever their name exists in the alphabet. Discord

group("toSetRoleHoist", () => {
  const role = {
    id: "12541612511",
    name: "tank",
  };

  test("should set role as hoist", () => {
    // role.name = hight-master
    expect(`setHoist ${role.id}`).toSetRoleHoist(true, role.id);
    expect(`setHoist ${role.id}`).toSetRoleHoist(true, { id: role.id });
    expect(`setHoist ${role.id}`).toSetRoleHoist(false, { name: role.name });
  });
});

`toSetRoleMentionable(boolean, string | RoleIdentifier)`

Use toSetRoleMentionable to check if a bot command set or not a role as mentionable.

Example mentionable role

group("toSetRoleMentionable", () => {
  const role = {
    id: "12541612511",
    name: "support 4",
  };

  test("should set role mentionable state", () => {
    expect(`setMentionable ${role.id}`).toSetRoleMentionable(true, role.id);
    expect(`setMentionable ${role.id}`).toSetRoleMentionable(true, { id: role.id });
    expect(`setMentionable ${role.id}`).toSetRoleMentionable(false, { name: role.name });
  });
});

`toSetRolePermission(string | RoleIdentifier, ...RolePermission[])`

Use toSetRolePermission to check if a bot command set or remove a single, or a list of permissions to a role.

Example permissions of role

group("toSetRolePermission", () => {
  const role = {
    id: "12541612511",
    name: "support 5",
  };

  test("should set role permissions", () => {
    expect(`setPermission VIEW_CHANNEL EMBED_LINKS`).toSetRolePermission(
      role.id,
      "VIEW_CHANNEL",
      "EMBED_LINKS",
    );
    expect(`setPermission VIEW_CHANNEL EMBED_LINKS`).toSetRolePermission(
      { id: role.id },
      "VIEW_CHANNEL",
      "EMBED_LINKS",
    );
    expect(`setPermission VIEW_CHANNEL EMBED_LINKS`).toSetRolePermission(
      { name: role.name },
      "VIEW_CHANNEL",
      "EMBED_LINKS",
    );
  });
});

Example permissions of role

`toSetRolePosition(number, string | RoleIdentifier)`

Use toSetRolePosition to check if a command changes a role's position.

group("toSetRolePosition", () => {
  const role = {
    id: "1231241241",
    name: "mid",
  };

  test("should set role position", () => {
    expect(`setPosition ${role.id}`).toSetRolePosition(1, role.id);
    expect(`setPosition ${role.id}`).toSetRolePosition(1, { id: role.id });
    expect(`setPosition ${role.id}`).toSetRolePosition(1, { name: role.name });
  });
});

Example role position

Message tests​

Role tests​

note

Reference​

expect(string | number | Function, customChannelId)​

note

inChannel(channelId)​

inGuild(guildId)​

not​

toHaveResult(expectReport)​

toAddReaction(emojis, messageIdentifier)​

note

toEditMessage(newContent, messageIdentifier)​

toPin(string | MessageIdentifier)​

toRemoveReaction(emojis, messageIdentifier)​

toReturn(string | boolean | number | messageEmbedSimple)​

toUnpin(string | MessageIdentifier)​

toDeleteRole(string | RoleIdentifier)​

toMessageContentContains(value)​

toEmbedMatch(embedMessage)​

toRenameRole(string, string | RoleIdentifier)​

toSetRoleColor(ColorResolvable | Colors, string | RoleIdentifier)​

toSetRoleHoist(boolean, string | RoleIdentifier)​

toSetRoleMentionable(boolean, string | RoleIdentifier)​

toSetRolePermission(string | RoleIdentifier, ...RolePermission[])​

toSetRolePosition(number, string | RoleIdentifier)​

Message tests

Role tests

Reference

`expect(string | number | Function, customChannelId)`

`inChannel(channelId)`

`inGuild(guildId)`

`not`

`toHaveResult(expectReport)`

`toAddReaction(emojis, messageIdentifier)`

`toEditMessage(newContent, messageIdentifier)`

`toPin(string | MessageIdentifier)`

`toRemoveReaction(emojis, messageIdentifier)`

`toReturn(string | boolean | number | messageEmbedSimple)`

`toUnpin(string | MessageIdentifier)`

`toDeleteRole(string | RoleIdentifier)`

`toMessageContentContains(value)`

`toEmbedMatch(embedMessage)`

`toRenameRole(string, string | RoleIdentifier)`

`toSetRoleColor(ColorResolvable | Colors, string | RoleIdentifier)`

`toSetRoleHoist(boolean, string | RoleIdentifier)`

`toSetRoleMentionable(boolean, string | RoleIdentifier)`

`toSetRolePermission(string | RoleIdentifier, ...RolePermission[])`

`toSetRolePosition(number, string | RoleIdentifier)`