Change the default for FakeFilesystem.shuffle_listdir_results to True

- reflects the real filesystem behavior

Author: mrbean-bremen

CHANGES.md

@@ -8,16 +8,14 @@ The released versions correspond to PyPI releases.
   these versions (usually several months after the official EOL); if the support is removed earlier
   (as with the change to version 6), patches for previous versions are provided if requested
 
-## Planned breaking changes for next major release (6.0.0)
-* the default for `FakeFilesystem.shuffle_listdir_results` will change to `True` to reflect
-  the real filesystem behavior
-
 ## Version 6.0.0 (unreleased)
 
 ### Breaking Changes
 * removed support for Python versions < 3.10; patch releases based pyfakefs 5.10
   supporting older versions may be made on demand
 * removed support for patching legacy modules `scandir` and `pathlib2`
+* changed the default for `FakeFilesystem.shuffle_listdir_results` to `True` to reflect
+  the real filesystem behavior
 
 ## [Version 5.10.0](https://pypi.python.org/pypi/pyfakefs/5.10.0) (2025-10-11)
 Adds official support for Python 3.14. Last minor version before the 6.0 release.

pyfakefs/fake_filesystem.py

@@ -190,8 +190,12 @@ class FakeFilesystem:
         patch_open_code: Defines how
             `io.open_code <https://docs.python.org/3/library/io.html#io.open_code>`__
             will be patched; patching can be on, off, or in automatic mode.
-        shuffle_listdir_results: If `True`, `os.listdir` will not sort the
-            results to match the real file system behavior.
+        shuffle_listdir_results: Set to `True` by default, meaning that the result order
+            is randomized to match the real file system behavior.
+            Setting it to `False` will cause `os.listdir` to sort the results. This is
+            discouraged and mainly there to retain upwards compatibility - relying on
+            the result order in tests is not recommended.
+            This attribute may be removed in a future version.
     """
 
     def __init__(
@@ -265,7 +269,7 @@ def __init__(
 
         # set from outside if needed
         self.patch_open_code = PatchMode.OFF
-        self.shuffle_listdir_results = False
+        self.shuffle_listdir_results = True
 
     @property
     def is_linux(self) -> bool:
@@ -3158,8 +3162,10 @@ def listdir(self, target_directory: AnyStr) -> list[AnyStr]:
 
         Returns:
             A list of file names within the target directory in arbitrary
-            order. If `shuffle_listdir_results` is set, the order is not the
-            same in subsequent calls to avoid tests relying on any ordering.
+            order. Per default, the order is not the same in subsequent calls.
+            This can be changed by setting `shuffle_listdir_results` to `False`
+            for testing convenience, though is not recommended to avoid accidentally
+            relying on any ordering in the production code.
 
         Raises:
             OSError: if the target is not a directory.