Write Flow Tests
Testing & Qualitywrite-flow-testsWrite Flow Tests is an Agent Skill for testing & quality published in the RediSearch/RediSearch repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Guidelines for writing Python flow tests (end-to-end behavioral tests). Use this when writing new Python tests in tests/pytests/.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/RediSearch/RediSearch/blob/HEAD/.skills/write-flow-tests/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/write-flow-tests, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Writing Python Flow Tests
Guidelines for writing new end-to-end Python flow tests in tests/pytests/.
Framework
Tests use the RLTest framework. The typical pattern is:
- Create an index with
env.expect('FT.CREATE', ...).ok() - Load data with
conn.execute_command('HSET', ...) - Assert query results with
env.cmd(...)orenv.expect(...)
Finding where to add tests
- Search existing test files in
tests/pytests/for related functionality using Grep (function names, command names, feature names). - Determine whether an existing test can be extended or a new test is needed.
- Look at nearby tests in the same file for style and patterns specific to that file.
Test function signature
- Accept
envas a parameter when the test works with the default environment (dialect 2 on CI):def testMyFeature(env): - Only create a custom
Env()when you need specific settings that differ from the default, such as:protocol=3(to accessres['warning']dicts)DEFAULT_DIALECT 1(to test legacy behavior)- Other non-default
moduleArgs
- Always document why a custom
Env()is needed if it's not obvious.
Cluster considerations
- Add
@skip(cluster=True)to tests that don't exercise cluster-specific behavior. This avoids redundant test runs. - If a test does need to run in cluster mode, use
{hash_tag}key prefixes (e.g.,{doc}:1) to ensure keys land on the same shard.
Index creation
- Use
env.expect('FT.CREATE', ...).ok()for creating indexes — notconn.execute_command('FT.CREATE', ...). - Reserve
conn(getConnectionByEnv(env)) for key-write commands likeHSET,DEL, etc.
Waiting for index
- Data inserted before
FT.CREATE: Background indexing is activated. CallwaitForIndex(env, 'idx')afterFT.CREATEto wait for the backfill to complete before querying. - Data inserted after
FT.CREATE: EachHSET/JSON.SETis immediately acknowledged by the index — nowaitForIndexneeded. - Do not call
waitForIndexright afterFT.CREATEwith no pre-existing data — there is nothing to wait for.
Assertions
- Compare the full result when the response is deterministic and small:
# Good — full result comparison res = env.cmd('FT.SEARCH', 'idx', '@t:{al*}', 'NOCONTENT') env.assertEqual(res, [1, 'doc1']) # Good — empty result res = env.cmd('FT.SEARCH', 'idx', '@t:{a*}', 'NOCONTENT') env.assertEqual(res, [0]) - Add
message=reswhen the assertion checks only part of the result (e.g.,assertGreaterEqual), so failures show the actual response:env.assertGreaterEqual(res[0], 9, message=res) - Use
env.expect(...).error().contains('...')for error-path tests. - Use
env.assertContains(...)for checking substrings in responses (e.g., warning messages, explain output).
Deprecated commands
- Do not use
FT.ADD— useHSETviaconn.execute_command('HSET', ...)instead. FT.ADDdoes not work in cluster mode and is deprecated.
Test structure
- Include a docstring explaining what code path or behavior the test exercises.
- Keep tests focused — one test per code path or behavior.
- Restore global config changes (e.g.,
MAXPREFIXEXPANSIONS) at the end of the test.