Tworzenie izolowanego projektu Python z venv i plikiem zależności

Cześć — oczywiście, cały kurs będziemy prowadzić po polsku. Zaczynamy od fundamentu, bez którego automatyzacja testów szybko staje się trudna do odtworzenia: każdy projekt potrzebuje własnego, izolowanego zestawu narzędzi i bibliotek.

W tej lekcji utworzysz katalog projektu, środowisko wirtualne .venv, zainstalujesz pierwsze zależności przez pip oraz zapiszesz ich wersje w requirements.txt. Taki układ będzie punktem wyjścia dla późniejszych testów z pytest, testów API i Playwright.

---

Dlaczego projekt potrzebuje własnego środowiska?

Biblioteki Pythona są rozwijane niezależnie. Jeden projekt może wymagać konkretnej wersji pytest, a inny — nowszej lub starszej wersji tej samej biblioteki. Gdyby wszystkie pakiety instalować globalnie, aktualizacja dla jednego projektu mogłaby zepsuć drugi.

Środowisko wirtualne (virtual environment) to prywatny obszar projektu zawierający:

• interpreter Pythona używany przez projekt,
• lokalnie instalowane pakiety,
• własne narzędzie pip.

Dzięki temu zależności projektu testowego nie mieszają się z pakietami innych projektów ani z instalacją systemową Pythona.

Przyjmij prostą zasadę pracy:

Jeden projekt Pythonowy — jedno środowisko .venv.

Ważne rozróżnienie:

Element	Rola
venv	moduł standardowej biblioteki Pythona, który tworzy izolowane środowisko
pip	menedżer pakietów: pobiera, instaluje i pokazuje pakiety
requirements.txt	tekstowa lista zależności i ich wersji potrzebna do odtworzenia środowiska
.venv/	lokalny katalog techniczny środowiska; nie zapisujemy go w repozytorium Git

Poniższa grafika pokazuje cały podstawowy cykl: tworzenie środowiska, aktywację, instalowanie pakietów, zapis zależności oraz ignorowanie katalogu środowiska przez Git.

---

Utworzenie katalogu projektu i .venv

Najpierw otwórz terminal. Może to być terminal systemowy albo wbudowany terminal edytora, np. Visual Studio Code. Utwórz katalog dla projektu i przejdź do niego:

mkdir testy-automatyczne
cd testy-automatyczne

Sprawdź, której wersji Pythona używasz:

python --version

Jeśli w Windows polecenie python nie działa, użyj zamiast niego:

py --version

W systemach macOS lub Linux czasem właściwym poleceniem jest:

python3 --version

Do utworzenia środowiska użyj interpretera, który ma być używany w projekcie:

python -m venv .venv

W Windows, jeśli korzystasz z programu uruchamiającego Python, odpowiednikiem może być:

py -m venv .venv

Polecenie ma trzy części:

1. python uruchamia wybrany interpreter.
2. -m venv poleca Pythonowi uruchomić wbudowany moduł do tworzenia środowiska.
3. .venv jest nazwą katalogu, w którym powstanie środowisko.

Nazwa .venv jest powszechną konwencją. Kropka na początku sprawia, że katalog jest mniej widoczny w wielu narzędziach, a jednocześnie jego przeznaczenie pozostaje jednoznaczne. Nie jest to nazwa wymagana technicznie — można użyć np. venv — ale warto stosować jedną konwencję we wszystkich projektach.

Po wykonaniu polecenia struktura projektu będzie przypominała:

testy-automatyczne/
└── .venv/

Katalog .venv zawiera pliki techniczne. Nie należy go ręcznie edytować ani kopiować między komputerami. Gdy środowisko ulegnie uszkodzeniu, zwykle najprościej je usunąć i utworzyć ponownie na podstawie requirements.txt.

---

Aktywacja: wybór właściwego Pythona i pip

Samo utworzenie .venv jeszcze nie przełącza terminala na to środowisko. Aktywacja tymczasowo ustawia ścieżkę terminala tak, aby komendy python i pip wskazywały narzędzia z .venv.

Użyj polecenia właściwego dla swojej powłoki.

Windows — Command Prompt:

.venv\Scripts\activate.bat

Windows — PowerShell:

.\.venv\Scripts\Activate.ps1

macOS i Linux — bash, zsh:

source .venv/bin/activate

Po aktywacji początek wiersza poleceń zwykle zawiera nazwę środowiska, na przykład:

(.venv) ...

To użyteczna wskazówka, ale nie traktuj jej jako jedynego potwierdzenia. Sprawdź faktycznie używany interpreter:

python -c "import sys; print(sys.executable)"

Wynik powinien zawierać ścieżkę do .venv. Sprawdź również pip:

python -m pip --version

Używaj formy:

python -m pip

zamiast samego:

pip

Obie formy zwykle działają po aktywacji, ale python -m pip ma istotną zaletę: jawnie łączy menedżer pakietów z interpreterem python, którego aktualnie używasz. Ogranicza to typowy problem: pakiet został zainstalowany przez jeden pip, a program uruchamiany jest przez innego Pythona.

Jeśli PowerShell blokuje uruchomienie skryptu aktywacyjnego przez politykę bezpieczeństwa, nie zmieniaj ustawień organizacji na stałe bez uzgodnienia. Możesz użyć Command Prompt albo postępować zgodnie z polityką zespołu. Aktywacja jest wygodna, lecz nie jedyna metoda korzystania ze środowiska: można też jawnie uruchomić .venv\Scripts\python w Windows lub .venv/bin/python w macOS/Linux.

Aby opuścić aktywne środowisko, wpisz:

deactivate

Zamknięcie terminala również kończy aktywację. Przy kolejnym otwarciu terminala nie tworzysz nowego .venv — tylko aktywujesz istniejące.

---

Instalacja zależności projektu testowego

W projekcie automatyzacji testów wkrótce przydadzą się:

• pytest do uruchamiania i organizowania testów,
• requests do wysyłania żądań HTTP w testach API.

Upewnij się, że środowisko jest aktywne, a potem zainstaluj oba pakiety:

python -m pip install pytest requests

pip pobierze wskazane biblioteki z PyPI, publicznego indeksu pakietów Pythona, oraz zainstaluje także ich zależności pośrednie. Na przykład pytest może wymagać dodatkowych bibliotek pomocniczych. Te pakiety również są częścią środowiska i powinny zostać uwzględnione przy jego odtwarzaniu.

Sprawdź, co zostało zainstalowane:

python -m pip list

Możesz także sprawdzić pojedynczy pakiet:

python -m pip show pytest

Wynik pokaże między innymi numer wersji i lokalizację instalacji. Lokalizacja powinna znajdować się wewnątrz .venv.

Na tym etapie nie musisz jeszcze pisać testu. Warto jednak wykonać krótką kontrolę, czy biblioteka jest widoczna dla Pythona. Utwórz plik sprawdz_srodowisko.py:

import requests

print(f"requests: {requests.__version__}")

Uruchom go z aktywowanym środowiskiem:

python sprawdz_srodowisko.py

Jeśli wyświetli się wersja requests, interpreter poprawnie korzysta z pakietu zainstalowanego w .venv.

---

requirements.txt: zapis środowiska, które da się odtworzyć

Sam katalog .venv jest lokalny dla Twojego komputera. Osoba pobierająca projekt z repozytorium nie powinna otrzymać gotowego katalogu środowiska, lecz przepis na jego odtworzenie. Tym przepisem jest plik requirements.txt.

Zapisz obecny stan zależności:

python -m pip freeze > requirements.txt

Znak > przekierowuje wynik polecenia do pliku. Zamiast wyświetlić listę w terminalu, system zapisze ją w requirements.txt.

Otwórz ten plik w edytorze. Zobaczysz wpisy podobne do:

pytest==...
requests==...

Pojawią się też pakiety zależne od nich. Numery wersji będą inne w zależności od dnia instalacji i Twojego środowiska.

Zapis w formacie:

nazwa_pakietu==konkretna_wersja

ma duże znaczenie dla powtarzalności. Jeżeli Ty, koleżanka z zespołu i serwer CI zainstalujecie ten sam plik, wszyscy otrzymacie ten sam zestaw wersji bibliotek. To ogranicza sytuacje typu: „test działał lokalnie, ale nie działa w pipeline”.

Aby odtworzyć zależności w świeżo utworzonym środowisku, wystarczy:

python -m pip install -r requirements.txt

Opcja -r oznacza, że pip ma odczytać wymagania z pliku.

Pełny proces dla drugiego komputera lub nowego członka zespołu wygląda wtedy następująco:

1. Pobranie kodu projektu wraz z requirements.txt.
2. Utworzenie lokalnego środowiska .venv.
3. Aktywacja środowiska.
4. Instalacja poleceniem python -m pip install -r requirements.txt.

Nie kopiujemy .venv, ponieważ może zawierać ścieżki i pliki specyficzne dla systemu operacyjnego oraz użytej wersji Pythona. Kopiujemy i wersjonujemy requirements.txt, bo jest lekki, czytelny i odtwarza zależności.

---

Co trafia do Git, a co zostaje lokalnie?

Dodaj w głównym katalogu projektu plik .gitignore, jeśli jeszcze go nie masz. Na początek wpisz do niego:

.venv/
__pycache__/

Pierwsza linia zapobiega dodawaniu całego środowiska wirtualnego do repozytorium. Druga ignoruje katalogi z plikami pomocniczymi tworzonymi przez Pythona.

Docelowa struktura po tej lekcji może wyglądać tak:

testy-automatyczne/
├── .gitignore
├── requirements.txt
├── sprawdz_srodowisko.py
└── .venv/

W Git zapisujesz:

• kod projektu,
• requirements.txt,
• .gitignore,
• później: testy, konfigurację i dokumentację.

Lokalnie pozostają:

• .venv/,
• tymczasowe pliki Pythona,
• sekrety i dane dostępowe, gdy zaczniemy pracować z prawdziwymi środowiskami testowymi.

Jeżeli przypadkowo dodasz .venv do Git przed utworzeniem .gitignore, samo dopisanie reguły ignorowania nie usunie już śledzonych plików. W takim przypadku usuwa się je z indeksu Git, zachowując lokalnie:

git rm -r --cached .venv

---

Checklista gotowego projektu

Przed przejściem dalej sprawdź, czy możesz potwierdzić każdy punkt:

• katalog projektu istnieje;
• w jego głównym katalogu istnieje .venv;
• po aktywacji python -c "import sys; print(sys.executable)" wskazuje ścieżkę zawierającą .venv;
• python -m pip list pokazuje pytest i requests;
• istnieje requirements.txt utworzony przez python -m pip freeze;
• python -m pip install -r requirements.txt może odtworzyć pakiety;
• .venv/ znajduje się w .gitignore.

---

Utworzyłeś izolowany projekt Pythonowy, w którym venv oddziela zależności od innych projektów, pip je instaluje, a requirements.txt pozwala odtworzyć identyczne środowisko na innym komputerze lub w CI. To minimalny, ale profesjonalny punkt startowy dla automatyzacji testów.

W następnej lekcji przejdziemy do podstawowych struktur danych Pythona — list, słowników, zbiorów i krotek — oraz do tego, jak dobierać je do danych testowych.