feat: add pgTAP testing skill for database test patterns

[jumski]

Add pgTAP Testing Skill for Database Testing

Added a new Claude skill for pgTAP testing that provides comprehensive guidance for writing database tests in pgflow. The skill includes:

• Complete test structure patterns and examples
• Common assertion techniques for database testing
• Helper function documentation for test setup and verification
• Realtime event testing patterns
• Test organization and execution instructions

This skill will help developers write effective database tests using the pgTAP framework, with specific focus on pgflow testing patterns. The skill includes a detailed reference of helper functions in a separate markdown file.

Also updated the schema-dev skill to reference the new pgTAP testing skill for additional test patterns and helpers.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7bdc851

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[graphite-app]

Merge activity

• Nov 2, 8:57 PM UTC: jumski added this pull request to the Graphite merge queue.
• Nov 2, 8:58 PM UTC: CI is running for this pull request on a draft pull request (#299) due to your merge queue CI optimization settings.
• Nov 2, 8:59 PM UTC: Merged by the Graphite merge queue via draft PR: #299.

[jumski]

• feat: add pgTAP testing skill for database test patterns #298 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge:queue - adds this PR to the back of the merge queue
• hotfix:queue - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 7bdc851

Command	Status	Duration	Result
nx affected -t build --configuration=production...	✅ Succeeded	<1s	View ↗
nx affected -t lint typecheck test --parallel -...	✅ Succeeded	<1s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-11-02 20:59:20 UTC

[github-actions]

🔍 Preview Deployment: Website

✅ Deployment successful!

🔗 Preview URL: https://pr-298.pgflow.pages.dev

📝 Details:

• Branch: chore-extract-pgtap-skill
• Commit: 03e12175f9c641e4d52544c127f8fcd296b38006
• View Logs

_Last updated: _

[graphite-app]

The plan declares 2 tests but only 1 assertion is present. The results_eq() at line 82-86 is the only assertion. This mismatch will cause the test to fail with "Bad plan. You planned 2 tests but ran 1."

Fix by changing line 74 to:

select plan(1);

Suggested change

	begin;
	select plan(2);
	select pgflow_tests.reset_db();
	select pgflow_tests.setup_flow('sequential');
	-- Execute function
	select pgflow.start_flow('sequential', '"hello"'::jsonb);
	-- Test: Check created run
	select results_eq(
	$$ SELECT flow_slug, status from pgflow.runs $$,
	$$ VALUES ('sequential', 'started') $$,
	'Run should be created with correct status'
	);
	select finish();
	rollback;
	begin;
	select plan(1);
	select pgflow_tests.reset_db();
	select pgflow_tests.setup_flow('sequential');
	-- Execute function
	select pgflow.start_flow('sequential', '"hello"'::jsonb);
	-- Test: Check created run
	select results_eq(
	$$ SELECT flow_slug, status from pgflow.runs $$,
	$$ VALUES ('sequential', 'started') $$,
	'Run should be created with correct status'
	);
	select finish();
	rollback;

Spotted by Graphite Agent



Is this helpful? React 👍 or 👎 to let us know.

[graphite-app]

The plan declares 3 tests but only 1 assertion is present. The is() at lines 117-122 is the only assertion. This mismatch will cause the test to fail with "Bad plan. You planned 3 tests but ran 1."

Fix by changing line 98 to:

select plan(1);

Suggested change

	begin;
	select plan(3);
	select pgflow_tests.reset_db();
	select pgflow_tests.setup_flow('sequential');
	-- Start flow
	select pgflow.start_flow('sequential', '"hello"'::jsonb);
	-- Poll and start task
	select pgflow_tests.read_and_start('sequential');
	-- Complete task
	select pgflow.complete_task(
	(select run_id from pgflow.runs limit 1),
	'first',
	0,
	'{"result": "done"}'::jsonb
	);
	-- Test: Task completed
	select is(
	(select status from pgflow.step_tasks
	where step_slug = 'first' limit 1),
	'completed',
	'Task should be completed'
	);
	select finish();
	rollback;
	```
	begin;
	select plan(1);
	select pgflow_tests.reset_db();
	select pgflow_tests.setup_flow('sequential');
	-- Start flow
	select pgflow.start_flow('sequential', '"hello"'::jsonb);
	-- Poll and start task
	select pgflow_tests.read_and_start('sequential');
	-- Complete task
	select pgflow.complete_task(
	(select run_id from pgflow.runs limit 1),
	'first',
	0,
	'{"result": "done"}'::jsonb
	);
	-- Test: Task completed
	select is(
	(select status from pgflow.step_tasks
	where step_slug = 'first' limit 1),
	'completed',
	'Task should be completed'
	);
	select finish();
	rollback;

Spotted by Graphite Agent



Is this helpful? React 👍 or 👎 to let us know.

[graphite-app]

The plan declares 3 tests but only 2 assertions are present. There are two is() calls at lines 169-176 and 179-187. This mismatch will cause the test to fail with "Bad plan. You planned 3 tests but ran 2."

Fix by changing line 153 to:

select plan(2);

Suggested change

	begin;
	select plan(3);
	-- CRITICAL: Create partition before testing realtime
	select pgflow_tests.create_realtime_partition();
	select pgflow_tests.reset_db();
	select pgflow.create_flow('sequential');
	select pgflow.add_step('sequential', 'first');
	-- Capture run_id in temporary table
	with flow as (
	select * from pgflow.start_flow('sequential', '{}')
	)
	select run_id into temporary run_ids from flow;
	-- Test: Event was sent
	select is(
	pgflow_tests.count_realtime_events(
	'run:started',
	(select run_id from run_ids)
	),
	1::int,
	'Should send run:started event'
	);
	-- Test: Event payload is correct
	select is(
	(select payload->>'status'
	from pgflow_tests.get_realtime_message(
	'run:started',
	(select run_id from run_ids)
	)),
	'started',
	'Event should have correct status'
	);
	-- Cleanup
	drop table if exists run_ids;
	select finish();
	rollback;
	```
	begin;
	select plan(2);
	-- CRITICAL: Create partition before testing realtime
	select pgflow_tests.create_realtime_partition();
	select pgflow_tests.reset_db();
	select pgflow.create_flow('sequential');
	select pgflow.add_step('sequential', 'first');
	-- Capture run_id in temporary table
	with flow as (
	select * from pgflow.start_flow('sequential', '{}')
	)
	select run_id into temporary run_ids from flow;
	-- Test: Event was sent
	select is(
	pgflow_tests.count_realtime_events(
	'run:started',
	(select run_id from run_ids)
	),
	1::int,
	'Should send run:started event'
	);
	-- Test: Event payload is correct
	select is(
	(select payload->>'status'
	from pgflow_tests.get_realtime_message(
	'run:started',
	(select run_id from run_ids)
	)),
	'started',
	'Event should have correct status'
	);
	-- Cleanup
	drop table if exists run_ids;
	select finish();
	rollback;

Spotted by Graphite Agent



Is this helpful? React 👍 or 👎 to let us know.