Skip to content

Add chapter for pyfakefs alternatives to intro #1196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 9, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 33 additions & 2 deletions docs/intro.rst
Original file line number Diff line number Diff line change
Expand Up @@ -87,18 +87,49 @@ Limitations

- ``pyfakefs`` may not work correctly if file system functions are patched by
other means (e.g. using `unittest.mock.patch`) - see
:ref:`usage_with_mock_open` for more information
:ref:`usage_with_mock_open` for more information.

- ``pyfakefs`` will not work correctly with
`behave <https://github.com/behave/behave>`__ due to the way it loads
the steps, if any filesystem modules are imported globally in the steps or
environment files; as a workaround, you may load them locally inside the
test steps (see `this issue <https://github.com/pytest-dev/pyfakefs/issues/703>`__)
test steps (see `this issue <https://github.com/pytest-dev/pyfakefs/issues/703>`__).

- ``pyfakefs`` is not guaranteed to work correctly in multi-threading environments.
Specifically, it does not ensure concurrent write access to a file from different
threads, which is possible under Posix.


.. |br| raw:: html

<br />

Alternatives
------------
Given the above limitations, it is not always possible to use `pyfakefs` to emulate the
filesystem. There are other possibilities to test the filesystem that you may consider
instead, for example:

- Use temporary files in the temp directory of your OS. |br|
*Pros*: Is is relatively easy to setup new tests, and the temp files are not affecting the
functionality of the actual file system. Under POSIX systems, they are also cleaned up
periodically. |br|
*Cons*: It is slower because the actual disk is used, cleaning up after tests can be
a problem, and the filesystem lives in a fixed location, which cannot always be used
in the tested code.

- Use a RAM disk. |br|
*Pros*: It is memory-based and therefore fast, and can be set up to a clean state before
each test. |br|
*Cons*: The filesystem lives in a fixed location, which cannot always be used in the tested code.

- Use a filesystem abstraction like `PyFilesystem <https://github.com/PyFilesystem/pyfilesystem2/>`__. |br|
*Pros*: You can replace the real filesystem by a memory based filesystem in your tests,
which has the same advantages as using ``pyfakefs``. |br|
*Cons*: Your production code must use this abstraction, so this is more a consideration
for new projects.


History
-------
``pyfakefs`` was initially developed at Google by
Expand Down
Loading