Metadata-Version: 2.1
Name: fixturefilehandler
Version: 1.2.0
Summary: This project helps you to vacate specific file path or deploy resource file into specific file path when unit testing.
Home-page: https://github.com/yukihiko-shinoda/fixture-file-handler
Author: Yukihiko Shinoda
Author-email: yuk.hik.future@gmail.com
License: UNKNOWN
Description: # Fixture File Handler
        
        This project helps you to vacate specific file path or deploy resource file into specific file path when unit testing.
        
        ## Context
        
        The most popular setup / teardown tasks about file system on unit testing is
        almost 2 kinds.
        
        1. vacate specific file path for testing file export function
        2. deploy fixture file / directory into specific file path for testing file import /export function
        
        Then we have to think about how to back up existing file / directory between unit testing
        because maybe developer wants to keep those handwritten files for development.
        
        `Fixture File Handler` is framework to realize simply implement
        the vacate and deploy actions while keeping the existing files.
        Of course, even if there is no file in the target path, it works fine.
        
        ## Ubiquitous Language
        
        ### target
        
        The target file path to vacate or deploy file / directory for unit testing.
        
        ### backup
        
        The file path to back up existing file / directory on target file path between unit testing.
        
        ### resource
        
        The file / directory you want to deploy and let product code read / write in unit testing.
        It may test resource file or template file like `*.dist` file.
        
        ## Basic behavior
        
        ### Vacator
        
        target path|backup path
        ---|---
        existing file /dir|&nbsp;
        
        ↓ setup
        
        target path|backup path
        ---|---
        &nbsp;|existing file / dir
        
        ↓ teardown
        
        target path|backup path
        ---|---
        existing file / dir|&nbsp;
        
        
        ### Deployer
        
        target path|backup path|resource path
        ---|---|---
        existing file / dir|&nbsp;|resource file / dir
        
        ↓ setup
        
        target path|backup path|resource path
        ---|---|---
        resource file / dir|existing file /dir|resource file / dir
        
        ↓ teardown
        
        target path|backup path|resource path
        ---|---|---
        existing file / dir|&nbsp;|resource file / dir
        
        
        ### Common behavior
        
        If file / directory already exists on backup path,
        setup raise `BackupAlreadyExistError`
        because it's unexpected situation and developer may want to resque those backup files.
        
        ## Quickstart
        
        #### 1. Install
        `pip install fixturefilehandler`
        
        #### 2-1. Case when unittest: implement setUp() and doCleanups()
        
        ```python
        from pathlib import Path
        import unittest
        
        from fixturefilehandler.factories import VacatorFactory
        from fixturefilehandler.file_paths import RelativeVacateFilePath
        
        VACATOR = VacatorFactory.create(
            RelativeVacateFilePath(
                Path('test.txt'),
                Path('test.txt.bak'),
                Path(__file__).parent
            )
        )
        
        
        class ConfigurableTestCase(unittest.TestCase):
            def setUp(self):
                VACATOR.setup()
        
            def doCleanups(self):
                VACATOR.teardown()
        ```
        
        #### 2-2. Case when pytest: implement fixture
        
        ```python
        from pathlib import Path
        import pytest
        
        from fixturefilehandler.factories import DeployerFactory
        from fixturefilehandler.file_paths import RelativeDeployFilePath
        
        DEPLOYER = DeployerFactory.create(
            RelativeDeployFilePath(
                Path('test.txt'),
                Path('test.txt.bak'),
                Path('testresources/test.txt.dist'),
                Path(__file__).parent
            )
        )
        
        
        @pytest.fixture
        def fixture_file():
            DEPLOYER.setup()
            yield DEPLOYER.FILE_PATH
            DEPLOYER.teardown()
        
        
        def test_something(fixture_file):
            """test something"""
        ```
        
        ## API
        
        ### file_paths
        
        #### SimpleVacateFilePath
        
        This instance holds path to target and backup.
        Each path is independent each other.
        
        #### SimpleDeployFilePath
        
        This instance holds path to target, backup, and resource.
        Each path is independent each other.
        
        #### RelativeVacateFilePath
        
        This instance holds path to target, backup, and base.
        Each path is relative based on base path.
        
        #### RelativeDeployFilePath
        
        This instance holds path to target, backup, resource, and base.
        Each path is relative based on base path.
        
        ## How do I...
        
        ### Use different paths for each test?
        
        `setup()` and `teardown()` also accept file_paths argument.
        
        Case when unittest:
        
        ```python
        from pathlib import Path
        
        import unittest
        
        from fixturefilehandler import ResourceFileDeployer
        from fixturefilehandler.file_paths import RelativeDeployFilePath
        
        
        class AdvancedConfigurableTestCase(unittest.TestCase):
            @property
            def file_path(self) -> RelativeDeployFilePath:
                return RelativeDeployFilePath(
                    Path('test.txt'),
                    Path('test.txt.bak'),
                    Path(f'testresources/{self._testMethodName}.txt'),
                    Path(__file__).parent
                )
        
            def setUp(self):
                ResourceFileDeployer.setup(self.file_path)
        
            def doCleanups(self):
                ResourceFileDeployer.teardown(self.file_path)
        ```
        
        Case when pytest:
        
        ```python
        from pathlib import Path
        
        import pytest
        
        from fixturefilehandler import ResourceFileDeployer
        from fixturefilehandler.file_paths import RelativeDeployFilePath
        
        
        @pytest.fixture
        def fixture_file_advanced(request):
            file_path = RelativeDeployFilePath(
                Path('test.txt'),
                Path('test.txt.bak'),
                Path(f'testresources/{request.node.name}.txt'),
                Path(__file__).parent
            )
        
            ResourceFileDeployer.setup(file_path)
            yield file_path
            ResourceFileDeployer.teardown(file_path)
        
        
        def test_something(fixture_file_advanced):
            """test something"""
        ```
Keywords: fixture file vacate deploy unittest pytest testing
Platform: UNKNOWN
Requires-Python: >3.6.0
Description-Content-Type: text/markdown
