Skip to content

contributing: Add a testing guide for vector attributes and temporal - #7961

Open
Valyrian-Code wants to merge 10 commits into
OSGeo:mainfrom
Valyrian-Code:testing-guide-database
Open

Valyrian-Code wants to merge 10 commits into
OSGeo:mainfrom
Valyrian-Code:testing-guide-database

Conversation

@Valyrian-Code

@Valyrian-Code Valyrian-Code commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Adds testing guide sections on vector attributes and temporal data, and updates the data files paragraph, which said files worked only with gunittest.

  • Data files go in a data directory next to the test, as in temporal/t.rast.import/tests.
  • The attribute and temporal databases are stored in the mapset by default, so a module-scoped session shares them across its tests.
  • grass.temporal reads the session from os.environ, so tests mirror it with monkeypatch.

Placed before "Tests which run in parallel" to stay clear of #7922.

Covers what a test has to set up for attribute tables and for the temporal
database: that the temporal database lives in the mapset and so is shared by
a module-scoped session, that t.create creates it, and that grass.temporal
reads the session from os.environ so a fixture has to mirror it with
monkeypatch.

Addresses the database half of OSGeo#7861. The network half is left for someone
who has written such a test.
Copilot AI lite review requested due to automatic review settings September 27, 2026 20:58
@github-actions github-actions Bot added docs markdown Related to markdown, markdown files labels Sep 27, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Revise the documented vector-table setup and temporal database prerequisite.

Review effort: Lite
Findings: 2 Low severity

Open (2)
What changed in this PR

Adds database-focused testing guidance for GRASS contributors.

Changes:

  • Documents vector attribute-table setup.
  • Explains temporal database initialization and mapset scoping.
  • Covers environment mirroring with monkeypatch.
File Description
doc/​development/​testing.md Adds the database testing guide section.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread doc/development/testing.md Resolved
Comment thread doc/development/testing.md Resolved
Clarified the relationship between vector geometry and attribute tables in tests, specifying the need to create the attribute table separately.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Comment thread doc/development/testing.md Resolved
@wenzeslaus

Copy link
Copy Markdown
Member

The linked issue likely means databases as in Postgres, not merely testing the APIs which hide things like vector attribute storage. I did not eval how useful the current content is.

tgis.init() creates the mapset's temporal database when there is none, and
the t.* tools call it first, so the section was directing people to setup
they do not need. Keep the location, since it explains why a module-scoped
session shares one database. Also wrap the attribute paragraph.
@Valyrian-Code

Copy link
Copy Markdown
Contributor Author

You are right, the issue is about Postgres and this is not that. I had read it as the setup a fixture needs before touching stored attributes.

Happy to narrow and retitle it, or close it and leave #7861 for someone who can write the Postgres part.

Fixed the two Copilot points meanwhile: v.random really does give a map with no table, and tgis.init() creates the database itself, so t.create was never the prerequisite I claimed. Long line wrapped.

@wenzeslaus wenzeslaus left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is useful, but just the sections need to be better and the current text confuses attributes and temporal databases. There are similarities - parallels even - but major differences, too.

The per-mapset isolation is common to both, although for attributes, the solution is either separate mapsets or actually not going with the defaults and switching to per-map database (I would be interested in seeing analysis for that, slower? breaks for some things?).

Otherwise, "test with the default backend unless testing the backend" is applicable to both vector attributes and temporal data (but I would think that's around where it ends, rest would be different, so again two sections are more appropriate).

Comment thread doc/development/testing.md Resolved
Comment thread doc/development/testing.md Resolved
Vector attributes and temporal data share per-mapset isolation and the
advice to test the default backend, but they are separate implementations,
so they get a section each instead of one section about databases.

Drop the parts which describe how the temporal database works rather than
what a test has to do about it, and say that a map from v.random or v.edit
has no attribute table and that the first table defines the connection for
the mapset.
@Valyrian-Code

Copy link
Copy Markdown
Contributor Author

Split in two, one section each, and dropped the parts describing how the temporal database works rather than what a test needs. Both say to test the default backend.

Left the per-map database out since I have not measured it. Can look at that separately if you want the numbers.

@Valyrian-Code

Copy link
Copy Markdown
Contributor Author

Measured it on 20 maps of 200 points. Build 1.01x, read 1.02x, so not slower.

It does break v.db.join across maps, since the other table is in a different file.

Also only the directory form works, vector/$MAP/sqlite.db. sqlite/$MAP.db fails because v.db.addtable replaces "$MAP/" with the slash, while field.c and pygrass replace a bare $MAP. Can file that separately.

The guide said data supplied as files is possible only with grass.gunittest.
It is not: temporal/t.rast.import/tests reads its data from a directory next
to the test, and pyproject.toml already excludes */tests/data/* from
collection.

Says how to do it instead, and leaves the North Carolina sample dataset as
the one reason left to reach for gunittest.

@wenzeslaus wenzeslaus left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be the last round.

Comment thread doc/development/testing.md Resolved
Comment thread doc/development/testing.md Resolved
Comment thread doc/development/testing.md Resolved
@wenzeslaus wenzeslaus changed the title contributing: Add a testing guide section on databases contributing: Add a testing guide for vector attributes and temporal Nov 12, 2026
The paragraph on data files no longer points to a specific test. The
approach works, as temporal/t.rast.import/tests shows, which reads its
archive from a data directory next to the test. The sentence on passing
the path is gone, and the temporal section now says that the database is
stored in the mapset by default, like the attribute tables.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs markdown Related to markdown, markdown files

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants