Merge pull request Agoric#35 from Agoric/ta/debug-test

script to debug test images

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

buildTestImages.ts

@@ -2,7 +2,7 @@
 
 import { parseArgs } from 'node:util';
 import { execSync } from 'node:child_process';
-import { imageNameForProposalTest, readProposals } from './common';
+import { imageNameForProposal, readProposals } from './common';
 import { refreshDockerfile } from './makeDockerfile';
 
 refreshDockerfile();
@@ -25,7 +25,7 @@ for (const proposal of proposals) {
   if (!dry) {
     console.log(`\nBuilding test image for proposal ${proposal.proposalName}`);
   }
-  const { name, target } = imageNameForProposalTest(proposal);
+  const { name, target } = imageNameForProposal(proposal, 'test');
   // 'load' to ensure the images are output to the Docker client. Seems to be necessary
   // for the CI docker/build-push-action to re-use the cached stages.
   const cmd = `docker buildx build --load --tag ${name} --target ${target} .`;

common.ts

@@ -45,15 +45,28 @@ 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/));
   assert(last, 'no passed proposals');
   return last;
 }
 
-export function imageNameForProposalTest(proposal) {
-  const target = `test-${proposal.proposalName}`;
+export function imageNameForProposal(
+  proposal: ProposalCommon,
+  stage: 'test' | 'eval',
+) {
+  const target = `${stage}-${proposal.proposalName}`;
   return {
     name: `${repository}:${target}`,
     target,

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' });

makeDockerfile.ts

@@ -99,7 +99,7 @@ WORKDIR /usr/src/upgrade-test-scripts
 COPY --link ./upgrade-test-scripts/install_deps.sh /usr/src/upgrade-test-scripts/
 RUN --mount=type=cache,target=/root/.yarn ./install_deps.sh ${proposalIdentifier}:${proposalName}
 
-COPY --link --chmod=755 ./upgrade-test-scripts/run_eval.sh /usr/src/upgrade-test-scripts/run_eval.sh
+COPY --link --chmod=755 ./upgrade-test-scripts/run_eval.sh /usr/src/upgrade-test-scripts/
 SHELL ["/bin/bash", "-c"]
 RUN ./run_eval.sh ${proposalIdentifier}:${proposalName}
 `;
@@ -127,7 +127,7 @@ COPY --link ./upgrade-test-scripts/lib /usr/src/upgrade-test-scripts/lib
 COPY --link ./upgrade-test-scripts/install_deps.sh /usr/src/upgrade-test-scripts/
 RUN --mount=type=cache,target=/root/.yarn ./install_deps.sh ${proposalIdentifier}:${proposalName}
 
-COPY --link --chmod=755 ./upgrade-test-scripts/run_use.sh /usr/src/upgrade-test-scripts/run_use.sh
+COPY --link --chmod=755 ./upgrade-test-scripts/run_use.sh /usr/src/upgrade-test-scripts/
 SHELL ["/bin/bash", "-c"]
 RUN ./run_use.sh ${proposalIdentifier}:${proposalName}
 `;
@@ -151,7 +151,8 @@ WORKDIR /usr/src/upgrade-test-scripts
 COPY --link ./upgrade-test-scripts/install_deps.sh /usr/src/upgrade-test-scripts/
 RUN --mount=type=cache,target=/root/.yarn ./install_deps.sh ${proposalIdentifier}:${proposalName}
 
-COPY --link --chmod=755 ./upgrade-test-scripts/run_test.sh /usr/src/upgrade-test-scripts/run_test.sh
+# copy run_test for this entrypoint and start_agd for optional debugging
+COPY --link --chmod=755 ./upgrade-test-scripts/run_test.sh ./upgrade-test-scripts/start_agd.sh /usr/src/upgrade-test-scripts/
 SHELL ["/bin/bash", "-c"]
 ENTRYPOINT ./run_test.sh ${proposalIdentifier}:${proposalName}
 `;
@@ -164,7 +165,7 @@ ENTRYPOINT ./run_test.sh ${proposalIdentifier}:${proposalName}
 # DEFAULT
 FROM use-${lastProposal.proposalName}
 
-COPY --link --chmod=755 ./upgrade-test-scripts/start_agd.sh /usr/src/upgrade-test-scripts/start_agd.sh
+COPY --link --chmod=755 ./upgrade-test-scripts/start_agd.sh /usr/src/upgrade-test-scripts/
 
 WORKDIR /usr/src/upgrade-test-scripts
 SHELL ["/bin/bash", "-c"]

runTestImages.ts

@@ -2,7 +2,7 @@
 
 import { parseArgs } from 'node:util';
 import { execSync } from 'node:child_process';
-import { imageNameForProposalTest, readProposals } from './common';
+import { imageNameForProposal, readProposals } from './common';
 
 const options = {
   match: { short: 'm', type: 'string' },
@@ -19,7 +19,7 @@ const proposals = match
 
 for (const proposal of proposals) {
   console.log(`Running test image for proposal ${proposal.proposalName}`);
-  const { name } = imageNameForProposalTest(proposal);
+  const { name } = imageNameForProposal(proposal, 'test');
   // 'rm' to remove the container when it exits
   const cmd = `docker run --rm ${name}`;
   execSync(cmd, { stdio: 'inherit' });

upgrade-test-scripts/start_agd.sh

@@ -6,5 +6,8 @@ grep -qF 'printKeys' /root/.bashrc || echo "printKeys" >>/root/.bashrc
 
 source ./env_setup.sh
 
+# start_agd never builds an image so it's safe to include this multigigabyte logfile
+export SLOGFILE=slog.slog
+
 # don't use startAgd() because that backgrounds
 agd start --log_level warn "$@"