Merge pull request #2 from cortze/extend-readme

Extend readme

Author: cortze

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+# Motivation
+<!-- Why are we developing this new code. Is the refactor needed, is the feature getting more data... -->
+
+
+_Related links:_
+- first link 
+
+# Description
+<!-- How are we approaching to solve the problem or deploy the new code -->
+<!-- What new structures will be added or what major changes will be applied -->
+
+# Tasks
+<!-- Checklist of tasks to do -->
+- [ ] first task 
+
+# Proof of Success 
+<!-- Here we may add any logs proving that we achieved what we expected or even diagrams that might be useful to understand the code -->

.github/workflows/module_tests.yml

@@ -1,7 +1,7 @@
 # taking as reference: https://github.com/actions/starter-workflows/blob/main/ci/python-package.yml
 name: Module Tests
 
-on: [push, pull_request]
+on: [push, merge_group]
 
 
 env:

README.md

@@ -1,2 +1,108 @@
-# dbtest
-Unittest wrapper focussed on DB integrity tests. Is your tool hard to debug? is it easier if you check it at the DB level? this module is for you
+# dbtest · ![](https://github.com/cortze/dbtest/actions/workflows/module_tests.yml/badge.svg) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Is your tool hard to debug? Is it easier if you check it at the DB level? 
+
+This module is for you! **dbtests** is a Python tool for conducting database tests. It is a unittest wrapper focussed on making DB integrity tests.
+As it is an extension over the `unittest.TestCase` it is easy to configure and easy to integrate with GitHub actions.
+
+
+
+## Features
+
+- It has an integrated connection to a Postgres Database: easily configurable using the `.env` file.
+- Fully compatible with `SQLAlchemy` and `Pandas`: get a `panda.Dataframe` out of any SQL query you want to test.
+- Unit-test oriented: Check if the `panda.Dataframe` output matches the expected values, or catch it when the test fails.
+
+## Installation
+
+You can install **dbtests** using pip:
+
+```bash
+pip install dbtests
+```
+
+## Usage
+Here's how you can use dbtests in your projects:
+
+1. Create a `./test` folder as with any other kind of `unittests` (it is in fact compatible with other `unittests` just make there is a connection to a Postgres DB), and create a `test-file`.
+```shell
+my-tool/
+├── my-tool/
+│   ├── __init__.py
+│   ├── script_1.py
+└── tests/
+    ├── __init__.py
+    └── test_script_1.py
+```
+
+2. Once the script is created, we need to import the dependencies:
+```python
+# test_script_1.py
+# Dependencies
+import unittest
+from dbtest.unittest import DBintegrityTest
+```
+
+3. Create a `DBintegrityTest` as if it was a `unittest.TestCase`. It is important to define the path to the `.env` that keeps the Postgres DB credentials:
+```python
+class TestDBTestModule(DBintegrityTest):
+    db_config_file = '.env'
+```
+
+4. Create as many `test` functions as pleased:
+```python
+    def test_not_null_items_in_column(self):
+        # the query that SHOULDN'T create an assertion
+        sql_query = """
+        SELECT 
+            id
+        FROM test_table;        
+        """
+        df = self.db.get_df_from_sql_query(sql_query)
+        self.assertNotNullItemsInColumn(df, 'id')
+
+if __name__ == '__main__':
+    unittest.main()
+```
+
+5. Run it as you please:
+```shell
+python -m unittest tests/test_script_1.py
+```
+
+The tests can be run locally or integrated with Github Actions. 
+For more examples, please check:
+- [Github Action example](./.github/workflows/module_tests.yml)
+- [Test example](./tests/module.py)
+
+## Custom Assert 
+The **dbtest** module contemplates new assert functions over `panda.Dataframe` objects. 
+This way the result of a simple query can be easily checked with the standard `unittest` nomenclature.
+
+The list of current Asserts is the following:
+- assertNotNullItemsInColumn(self, df, column)
+- assertCustomNullItemsInColumn(self, df, column, target)
+- assertNoRows(self, df)
+- assertNRows(self, df, target_rows)
+
+There will be more to come (under demand most probably). Feel free to suggest new ones though!
+
+
+## Contributing
+If you want to contribute to this project, please follow these guidelines:
+
+- Fork the repository
+- Create a new branch
+- Make your changes
+- Submit a pull request
+- Bugs and Issues
+
+If you encounter any bugs or issues, please report them here.
+
+## Contact
+Author: Mikel Cortes ([@cortze](https://github.com/cortze))
+
+Feel free to reach out if you have any questions or suggestions!
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.