diff --git a/templates/zerver/api/writing-bots.md b/templates/zerver/api/writing-bots.md index 68082ab9a0..8ceb6e2e7a 100644 --- a/templates/zerver/api/writing-bots.md +++ b/templates/zerver/api/writing-bots.md @@ -399,28 +399,30 @@ refactor them. Let's have a look at a simple test suite for the [`helloworld`]( https://github.com/zulip/python-zulip-api/tree/master/zulip_bots/zulip_bots/bots/helloworld) - bot (the actual test is written slightly more compact). + bot. - from __future__ import absolute_import + from zulip_bots.test_lib import StubBotTestCase - from zulip_bots.test_lib import BotTestCase # The test system library + class TestHelpBot(StubBotTestCase): + bot_name = "helloworld" # type: str - class TestHelloWorldBot(BotTestCase): - bot_name = "helloworld" # The bot's name (should be the name of the bot module to test). + def test_bot(self) -> None: + dialog = [ + ('', 'beep boop'), + ('help', 'beep boop'), + ('foo', 'beep boop'), + ] - def test_bot(self): # A test case (must start with `test`) - # Messages we want to test and the expected bot responses. - message_response_pairs = [("", "beep boop"), - ("foo", "beep boop"), - ("Hi, my name is abc", "beep boop")] - self.check_expected_responses(message_response_pairs) # Test the bot with our message_response_pair list. + self.verify_dialog(dialog) -The `helloworld` bot replies with "beep boop" to every message @-mentioning it. -Note that our helper method `check_expected_responses` adds the @-mention for us - the only -thing we need to do is to specify the rest of the message and the expected response. In this -case, we want to assert that the bot always replies with "beep boop". To do so, we specify -several test messages ("", "foo", "Hi, my name is abc") and assert that the response is always -correct, which for this simple bot, means always sending a reply with the content "beep boop". +The `helloworld` bot replies with "beep boop" to every message @-mentioning it. We +want our test to verify that the bot **actually** does that. + +Note that our helper method `verify_dialog` simulates the conversation for us, and +we just need to set up a list of tuples with expected results. + +The best way to learn about bot tests is to read all the existing tests in the +`bots` subdirectories. ### Testing your test @@ -430,8 +432,6 @@ Once you have written a test suite, you want to verify that everything works as https://github.com/zulip/python-zulip-api/tree/master/zulip_bots/zulip_bots/bots): `tools/test-bots ` -* To run any test: `python -m unittest -v ` - * To run all bot tests: `tools/test-bots` ### Advanced testing @@ -441,30 +441,20 @@ configuration files or interact with third-party APIs. *The code for the bot testing library can be found [here]( https://github.com/zulip/python-zulip-api/blob/master/zulip_bots/zulip_bots/test_lib.py).* -#### Asserting individual messages - - self.assert_bot_response( - message = {'content': 'foo'}, - response = {'content': 'bar'}, - expected_method='send_reply' - ) - -Use `assert_bot_response()` to test individual messages. Specify additional message -settings, such as the stream or subject, in the `message` and `response` dicts. #### Testing bots with config files Some bots, such as [Giphy]( https://github.com/zulip/python-zulip-api/tree/master/zulip_bots/zulip_bots/bots/giphy), -support or require user configuration options to control how the bot works. To test such -a bot, you can use the following helper method: +support or require user configuration options to control how the bot works. - with self.mock_config_info({'entry': 'value'}): - # self.assert_bot_response(...) +To test such a bot, you can use the following pattern: -`mock_config_info()` mocks a bot's config file. All config files are specified in the -.ini format, with one default section. The dict passed to `mock_config_info()` specifies -the keys and values of that section. + with self.mock_config_info(dict(api_key=12345)): + # self.verify_reply(...) + +`mock_config_info()` replaces the actual step of reading configuration from the file +system and gives your test "dummy data" instead. #### Testing bots with internet access @@ -486,17 +476,6 @@ https://github.com/zulip/python-zulip-api/tree/master/zulip_bots/zulip_bots/bots *Tip: You can use [requestb.in](http://requestb.in) or a similar tool to capture payloads from the service your bot is interacting with.* -#### Testing bots that specify `initialize()` - -Some bots, such as [Giphy]( -https://github.com/zulip/python-zulip-api/tree/master/zulip_bots/zulip_bots/bots/giphy), -implement an `initialize()` method, which is executed on the startup of the bot. To test -such a bot, you can call its `initialize()` method with the following helper method: - - self.initialize_bot() - -Calling `initialize_bot()` invokes the `initialize()` method specified by the bot. - #### Examples Check out our [bots](https://github.com/zulip/python-zulip-api/tree/master/zulip_bots/zulip_bots/bots)