wip: test: add manual test instructions, tidy repo

Private-ref: https://tasks.opencraft.com/browse/BB-10035

Author: samuelallan72

.github/pull_request_template.md

@@ -0,0 +1,29 @@
+## Description
+
+Describe what this pull request changes, and why. Include implications for people using this change.
+
+## Supporting information
+
+Link to other information about the change, such as Jira issues, GitHub issues, or Discourse discussions.
+Be sure to check they are publicly readable, or if not, repeat the information here.
+
+## Testing instructions
+
+Please provide detailed step-by-step instructions for testing this change.
+
+## Deadline
+
+"None" if there's no rush, or provide a specific date or event (and reason) if there is one.
+
+## Other information
+
+Include anything else that will help reviewers and consumers understand the change.
+
+- Does this change depend on other changes elsewhere?
+- Any special concerns or limitations? For example: deprecations, migrations, security, or accessibility.
+- If your [database migration](https://openedx.atlassian.net/wiki/spaces/AC/pages/23003228/Everything+About+Database+Migrations) can't be rolled back easily.
+
+## Pre-merge checklist:
+
+- [ ] `make format` has been run.
+- [ ] This has been manually installed in a Tutor devstack and manual testing steps have been followed (as described in the README).

Makefile

@@ -2,27 +2,19 @@
 
 .DEFAULT_GOAL := help
 
-# For opening files in a browser. Use like: $(BROWSER)relative/path/to/file.html
-BROWSER := python -m webbrowser file://$(CURDIR)/
-
 help: ## display this help message
 	@echo "Please use \`make <target>' where <target> is one of"
 	@awk -F ':.*?## ' '/^[a-zA-Z]/ && NF==2 {printf "\033[36m  %-25s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST) | sort
 
-clean: ## remove generated byte code, coverage reports, and build artifacts
+clean: ## remove generated byte code, build artifacts, etc.
 	find . -name '__pycache__' -exec rm -rf {} +
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
 	find . -name '*~' -exec rm -f {} +
-	coverage erase
 	rm -fr build/
 	rm -fr dist/
 	rm -fr *.egg-info
 
-coverage: clean ## generate and view HTML coverage report
-	pytest --cov-report html
-	$(BROWSER)htmlcov/index.html
-
 # Define PIP_COMPILE_OPTS=-v to get more information during make upgrade.
 PIP_COMPILE = pip-compile --rebuild --upgrade $(PIP_COMPILE_OPTS)
 
@@ -32,14 +24,10 @@ upgrade: ## update the requirements/*.txt files with the latest packages satisfy
 	# Make sure to compile files after any other files they include!
 	$(PIP_COMPILE) -o requirements/pip-tools.txt requirements/pip-tools.in
 	$(PIP_COMPILE) -o requirements/base.txt requirements/base.in
-	$(PIP_COMPILE) -o requirements/test.txt requirements/test.in
 	$(PIP_COMPILE) -o requirements/quality.txt requirements/quality.in
 	$(PIP_COMPILE) -o requirements/dev.txt requirements/dev.in
-	# Let tox control the Django version for tests
-	sed '/^[dD]jango==/d' requirements/test.txt > requirements/test.tmp
-	mv requirements/test.tmp requirements/test.txt
 
-quality: selfcheck ## check coding style with pycodestyle and pylint
+quality: selfcheck ## run static code quality checks
 	tox -e quality
 
 pii_check: ## check for PII annotations on all Django models
@@ -49,23 +37,12 @@ requirements: ## install development environment requirements
 	pip install -qr requirements/pip-tools.txt
 	pip-sync requirements/dev.txt requirements/private.*
 
-test: clean ## run tests in the current virtualenv
-	pytest
-
-diff_cover: test ## find diff lines that need test coverage
-	diff-cover coverage.xml
-
-test-all: quality ## run tests on every supported Python/Django combination
-	tox
-
-validate: quality test ## run tests and quality checks
-
 selfcheck: ## check that the Makefile is well-formed
 	@echo "The Makefile is well-formed."
 
+# NOTE: This needs to be run in an tutor dev environment
 test_migrations: ## check that Django migrations reflect all model changes
-	tox -e migrations
+	python ./manage.py makemigrations shoppingcart --check --dry-run --verbosity 3
 
 format: ## apply standard code formatting
-	isort shoppingcart setup.py manage.py tests test_utils test_settings.py
-	black shoppingcart setup.py manage.py tests test_utils test_settings.py
+	tox -e format

README.md

@@ -17,9 +17,39 @@ Updated for standalone, Juniper/Py3 by @bryanlandia
 
 See [apidocs.md](./appsembler_api/apidocs.md) for details on usage/the API
 
+## Installing in a devstack
+
+This assumes a [Tutor dev devstack](https://docs.tutor.edly.io/dev.html) set up.
+
+```
+git clone https://github.com/open-craft/legacy-appsembler-api
+tutor mounts add ./legacy-appsembler-api
+
+# This directory won't be autodetected for build-time mount by Tutor,
+# so we need to manually configure Tutor for it.
+mkdir -p "$TUTOR_PLUGINS_ROOT"
+echo 'from tutor import hooks; hooks.Filters.MOUNTED_DIRECTORIES.add_item(("openedx", "legacy-appsembler-api"))' > "$TUTOR_PLUGINS_ROOT/legacy-appsembler-api.py"
+tutor plugins enable legacy-appsembler-api
+
+tutor images build openedx-dev
+tutor dev launch
+```
+
 ## Testing
 
-For some tests you need to run them from within a working Open edX environment.
+Quality tests (runs within tox, so you can run it directly on your workstation):
+
+```
+make quality
+```
+
+---
+
+For unit/integration tests and migration tests,
+you need to run them from within a working Open edX environment.
+Note that the tests will make changes to the database. They should be automatically rolled back,
+but just in case, it's only recommended to run on a test deployment.
+
 Install in a Tutor devstack, then shell into the lms:
 
 ```sh
@@ -32,9 +62,9 @@ In the LMS shell, cd to the plugin directory:
 cd /mnt/legacy-appsembler-api
 ```
 
-Then you can run the unit tests (no unit tests yet):
+Then you can run the unit tests and migration tests:
 
 ```sh
-pytest
-python ./manage.py makemigrations shoppingcart --check --dry-run --verbosity 3
+make test
+make test_migrations
 ```

codecov.yml

@@ -1,2 +1,5 @@
 [tool.black]
 line-length = 120
+
+[tool.isort]
+profile = "black"

pyproject.toml

@@ -4,7 +4,7 @@
 #
 #    make upgrade
 #
-asgiref==3.9.1
+asgiref==3.9.2
     # via django
 django==4.2.24
     # via

requirements/base.txt

@@ -4,6 +4,5 @@
 -r pip-tools.txt          # pip-tools and its dependencies, for managing requirements files
 -r quality.txt            # Core and quality check dependencies
 
-diff-cover                # Changeset diff test coverage
 edx-i18n-tools            # For i18n_tool dummy
 tox-battery               # Makes tox aware of requirements file changes

requirements/dev.in

@@ -4,7 +4,7 @@
 #
 #    make upgrade
 #
-asgiref==3.9.1
+asgiref==3.9.2
     # via
     #   -r requirements/quality.txt
     #   django
@@ -62,7 +62,7 @@ cryptography==46.0.1
     # via
     #   -r requirements/quality.txt
     #   secretstorage
-diff-cover==9.6.0
+diff-cover==9.7.0
     # via -r requirements/dev.in
 dill==0.4.0
     # via
@@ -86,6 +86,12 @@ edx-i18n-tools==1.9.0
     # via -r requirements/dev.in
 edx-lint==5.6.0
     # via -r requirements/quality.txt
+factory-boy==3.3.3
+    # via -r requirements/quality.txt
+faker==37.8.0
+    # via
+    #   -r requirements/quality.txt
+    #   factory-boy
 filelock==3.19.1
     # via
     #   tox
@@ -324,6 +330,10 @@ tox-battery==0.6.2
     # via -r requirements/dev.in
 twine==6.2.0
     # via -r requirements/quality.txt
+tzdata==2025.2
+    # via
+    #   -r requirements/quality.txt
+    #   faker
 urllib3==2.5.0
     # via
     #   -r requirements/quality.txt

requirements/dev.txt

@@ -6,7 +6,5 @@
 black
 edx-lint                  # edX pylint rules and plugins
 isort                     # to standardize order of imports
-pycodestyle               # PEP 8 compliance validation
-pydocstyle                # PEP 257 compliance validation
 pylint
 twine                     # Utility for publishing Python packages on PyPI.

requirements/quality.in

@@ -4,7 +4,7 @@
 #
 #    make upgrade
 #
-asgiref==3.9.1
+asgiref==3.9.2
     # via
     #   -r requirements/test.txt
     #   django
@@ -54,6 +54,12 @@ docutils==0.22.2
     # via readme-renderer
 edx-lint==5.6.0
     # via -r requirements/quality.in
+factory-boy==3.3.3
+    # via -r requirements/test.txt
+faker==37.8.0
+    # via
+    #   -r requirements/test.txt
+    #   factory-boy
 id==1.5.0
     # via twine
 idna==3.10
@@ -200,6 +206,10 @@ tomlkit==0.13.3
     # via pylint
 twine==6.2.0
     # via -r requirements/quality.in
+tzdata==2025.2
+    # via
+    #   -r requirements/test.txt
+    #   faker
 urllib3==2.5.0
     # via
     #   requests