Skip to content
Skills Library
Programming · Testing

write-flow-tests

/write-flow-tests

Guidelines for writing Python flow tests (end-to-end behavioral tests). Use this when writing new Python tests in tests/pytests/, and as the review criteria when reviewing changes to them.

Repository
RediSearch ↗
Licence
AGPL-3.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

Guidelines for writing Python flow tests (end-to-end behavioral tests). Use this when writing new Python tests in tests/pytests/, and as the review criteria when reviewing changes to them.

Original author description

Guidelines for writing Python flow tests (end-to-end behavioral tests). Use this when writing new Python tests in tests/pytests/, and as the review criteria when reviewing changes to them.

How it works

  1. Framework
  2. Finding where to add tests
  3. Test function signature
  4. Cluster considerations
  5. Index creation
  6. Waiting for index
  7. Assertions
  8. Determinism
  9. Deprecated commands
  10. Test structure
Original SKILL.md headings · 84 lines, 528 words
SKILL.md preview
---
name: write-flow-tests
description: Guidelines for writing Python flow tests (end-to-end behavioral tests). Use this when writing new Python tests in tests/pytests/, and as the review criteria when reviewing changes to them.
---

# 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:
1. Create an index with `env.expect('FT.CREATE', ...).ok()`
2. Load data with `conn.execute_command('HSET', ...)`
3. Assert query results with `env.cmd(...)` or `env.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 `env` as a parameter when the test works with the default environment (dialect 2 on CI):
  ```python
  def testMyFeature(env):
  ```
- Only create a custom `Env()` when you need specific settings that differ from the default, such as:
  - `protocol=3` (to access `res['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 — not `conn.execute_command('FT.CREATE', ...)`.
- Reserve `conn` (`getConnectionByEnv(env)`) for key-write commands like `HSET`, `DEL`, etc.

## Waiting for index

- **Data inserted before `FT.CREATE`**: Background indexing is activated. Call `waitForIndex(env, 'idx')` after `FT.CREATE` to wait for the backfill to complete before querying.
- **Data inserted after `FT.CREATE`**: Each `HSET`/`JSON.SET` is immediately acknowledged by the index — no `waitForIndex` needed.
- Do not call `waitForIndex` right after `FT.CREATE` with no pre-existing data — there is nothing to wait for.

## Assertions

- **Compare the full result** when the response is deterministic and small:
  ```python
  # 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=res`** when the assertion checks only part of the result (e.g., `assertGreaterEqual`), so failures show the actual response:
  ```python
  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).

## Determinism

A test must pass, or fail, for the same reason on every machine. Anything host-speed
dependent — a wall-clock `TIMEOUT`, a sleep, a race with background indexing or GC — should
prefer a deterministic hook instead; grep `_FT.DEBUG` in `tests/pytests/` for what exists,
and check the one you pick reaches the code path under test.

## Deprecated commands

- Do not use `FT.ADD` — use `HSET` via `conn.execute_command('HSET', ...)` instead.
- `FT.ADD` does 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 — tests in a file share one server.

Versions

The database has no other skills named write-flow-tests.

Database snapshot: 13.11.2026 · package version 22f6a942107e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100run-python-tests
    Run end-to-end Python tests after making changes to verify correctness. Use this when you want to verify your changes from an end-to-end perspective, after ensuring the build and Rust tests pass.
  • 100python-testing
    Guidelines for writing and running tests in the Agent Framework Python codebase. Use this when creating, modifying, or running tests.
  • 100write-tests
    Guide for writing unit tests. Use this when creating tests to verify Python logic.
  • 100check-flow-coverage
    Check which C source lines are not covered by Python flow tests. Use this when you want to ensure your C code changes are exercised by end-to-end Python tests. For Rust coverage, use /check-rust-coverage instead.
  • 90write-e2e-test
    Create, maintain, and verify end-to-end (E2E) tests using Playwright MCP. Use when a new feature or flow needs E2E coverage, when updating flows, or verifying UI and functional correctness.
  • 96python-tests
    Python tests for NeMo Fabric; use this when writing tests

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.