From 50c17bbd08700a3210fdfd35553fcf761343086d Mon Sep 17 00:00:00 2001
From: Egor Tensin <egor@tensin.name>
Date: Tue, 22 Jul 2025 23:36:45 +0200
Subject: DEVELOPMENT: clarify testing a bit

---
 DEVELOPMENT.md          | 39 +++++++++++++++++++++++++++++----------
 test/set_credentials.sh | 13 +++++++++++++
 2 files changed, 42 insertions(+), 10 deletions(-)
 create mode 100644 test/set_credentials.sh

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index e88be2f..2641a1a 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -4,12 +4,31 @@ Workspace setup
 * Create a virtual Python environment: `make venv`
 * Use the virtual environment: `. .venv/bin/activate`
     * Deactivate the environment when you're done: `deactivate`
-* Make sure basic tests work: `make test`
 
-Development
------------
+Testing
+-------
+
+N.B.: `make test` is a shortcut for unit tests and the `local` integration
+test.
+
+### Unit tests
+
+    make test/unit
+
+You need to set the following environment variables for the authenticated
+access tests to work:
+
+* `CGITIZE_BITBUCKET_USERNAME`: `cgitize-test`
+* `CGITIZE_BITBUCKET_TOKEN`
+* `CGITIZE_GITHUB_USERNAME`: `cgitize-test`
+* `CGITIZE_GITHUB_TOKEN`
+* `CGITIZE_GITLAB_USERNAME`: `cgitize-test`
+* `CGITIZE_GITLAB_TOKEN`
+
+You can run `. test/set_credentials.sh`; it'll ask you to fill in the secrets.
+
+### Integration
 
-* Run unit tests: `make test/unit`
 * There're three integration tests: `local`, `docker` and `example`.
 Run them using
 
@@ -17,13 +36,13 @@ Run them using
       sudo make test/docker
       make test/example
 
-    * The `example` test uses the forges' APIs and might easily hit rate
+    * The `example` test uses the forges' APIs and might easily hit their rate
 limits.
-Set environment variables described in [examples/cgitize.toml] to use "access
-tokens" and get much higher rate limits.
-    * Run both unit tests and the `local` test using
-
-          make test
+Use the tokens used for unit tests.
+    * Additionally, it tests cloning via SSH (the `clone_via_ssh` setting) too,
+so you need to add the secret project-specific SSH key to your agent as well
+(make sure it's the only one in the agent; if there's a key associated with
+another user, it could get used instead).
 
 [examples/cgitize.toml]: examples/cgitize.toml
 
diff --git a/test/set_credentials.sh b/test/set_credentials.sh
new file mode 100644
index 0000000..1d8fd87
--- /dev/null
+++ b/test/set_credentials.sh
@@ -0,0 +1,13 @@
+IFS= read -r -s -p 'Bitbucket token: ' CGITIZE_BITBUCKET_TOKEN
+echo
+IFS= read -r -s -p 'GitHub token: ' CGITIZE_GITHUB_TOKEN
+echo
+IFS= read -r -s -p 'GitLab token: ' CGITIZE_GITLAB_TOKEN
+echo
+
+export CGITIZE_BITBUCKET_USERNAME=cgitize-test
+export CGITIZE_BITBUCKET_TOKEN
+export CGITIZE_GITHUB_USERNAME=cgitize-test
+export CGITIZE_GITHUB_TOKEN
+export CGITIZE_GITLAB_USERNAME=cgitize-test
+export CGITIZE_GITLAB_TOKEN
-- 
cgit v1.2.3