feat: debug test image

README.md

@@ -74,7 +74,15 @@ To run the tests for particular proposals,
 ./runTestImages.ts --match upgrade
 ```
 
-## Contributing
+## Debugging
+
+To get the local files into the container, use a [bind mount](https://docs.docker.com/storage/bind-mounts/). E.g.
+
+```
+docker run -it --entrypoint bash --mount type=bind,src=.,dst=/usr/src/a3p ghcr.io/agoric/agoric-3-proposals:use-upgrade-8
+```
+
+# Contributing
 
 To add a proposal, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
@@ -102,7 +110,6 @@ docker run  ghrc.io/agoric/agoric-3-proposals:dev
 ## Future work
 
 - [ ] include a way to test soft patches that weren't proposals (e.g. PismoB)
-- [ ] documentation and tooling for debugging
 - [ ] separate console output for agd and the scripts (had been with tmux before but trouble, try Docker compose https://github.com/Agoric/agoric-sdk/discussions/8480#discussioncomment-7438329)
 - [ ] way to query capdata in one shot (not resorting to follow jsonlines hackery)
 - [ ] within each proposal, separate dirs for supporting files so images don't invalidate

common.ts

@@ -45,6 +45,16 @@ export function readProposals(): ProposalInfo[] {
   return proposalPaths.map(readInfo);
 }
 
+export const readOneProposal = (match: string) => {
+  const allProposals = readProposals();
+
+  const proposals = allProposals.filter(p => p.proposalName.includes(match));
+
+  assert(proposals.length > 0, 'no proposals match');
+  assert(proposals.length === 1, 'too many proposals match');
+  return proposals[0];
+};
+
 export function lastPassedProposal(proposals: ProposalInfo[]): ProposalInfo {
   // @ts-expect-error use es2023; findLast is available in Node 18
   const last = proposals.findLast(p => p.proposalIdentifier.match(/^\d/));

debugTestImage.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env tsx
+/**
+ * @file like runTestImages.ts, but for a single proposal,
+ * and leaves the chain running
+ */
+import { execSync } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { imageNameForProposal, readOneProposal } from './common';
+
+const options = {
+  match: { short: 'm', type: 'string' },
+} as const;
+const { values } = parseArgs({ options });
+
+const proposal = readOneProposal(values.match!);
+const { name } = imageNameForProposal(proposal, 'test');
+
+console.log(
+  `
+Starting chain of test image for proposal ${proposal.proposalName}
+
+To get an interactive shell in the container, use an IDE feature like "Attach Shell" or this command:'
+
+  docker exec -ti $(docker ps -q -f ancestor=${name}) bash
+
+And within that shell:
+  cd /usr/src/proposals/<PROPOSAL_PATH> && ./test.sh
+
+The 'proposals' path is mounted in the container so your edits will appear there.
+`,
+);
+
+// start the chain, with the repo mounted at /usr/src
+const cmd = `docker run --mount type=bind,src=./proposals,dst=/usr/src/proposals -it --entrypoint /usr/src/upgrade-test-scripts/start_agd.sh ${name}`;
+execSync(cmd, { stdio: 'inherit' });