Skip to content

Commit

Permalink
feat(docs): add --dryRun option (#454)
Browse files Browse the repository at this point in the history 
* fix(docs): return formatted strings in success output

We're going to consistently return strings here instead of the total raw dump of the doc objects. it's not very intuitive nor readable, and by being able to consistently return strings that we can format, it'll set up the dry run functionality quite nicely.

* feat(docs): add `dryRun` option

* test: backfill some long overdue TODOs

* test: dry run tests

* chore: PR feedback

#454 (comment)
  • Loading branch information
@kanadgupta
kanadgupta authored Mar 1, 2022
1 parent 154aa0f commit f86b5c6
Show file tree
Hide file tree
Showing 2 changed files with 165 additions and 41 deletions.
165 changes: 133 additions & 32 deletions __tests__/cmds/docs.test.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,25 @@ describe('rdme docs', () => {
);
});

it.todo('should error if the argument isnt a folder');
it('should error if the argument isnt a folder', async () => {
const versionMock = getApiNock().get(`/api/v1/version/${version}`).basicAuth({ user: key }).reply(200, { version });

await expect(docs.run({ key, version: '1.0.0', folder: 'not-a-folder' })).rejects.toThrow(
"ENOENT: no such file or directory, scandir 'not-a-folder'"
);

versionMock.done();
});

it('should error if the folder contains no markdown files', async () => {
const versionMock = getApiNock().get(`/api/v1/version/${version}`).basicAuth({ user: key }).reply(200, { version });

await expect(docs.run({ key, version: '1.0.0', folder: '.github/workflows' })).rejects.toThrow(
'We were unable to locate Markdown files in .github/workflows.'
);

it.todo('should error if the folder contains no markdown files');
versionMock.done();
});

describe('existing docs', () => {
let simpleDoc;
Expand Down Expand Up @@ -112,21 +128,56 @@ describe('rdme docs', () => {
return docs.run({ folder: './__tests__/__fixtures__/existing-docs', key, version }).then(updatedDocs => {
// All docs should have been updated because their hashes from the GET request were different from what they
// are currently.
expect(updatedDocs).toStrictEqual([
{
category,
slug: simpleDoc.slug,
body: simpleDoc.doc.content,
},
{ category, slug: anotherDoc.slug, body: anotherDoc.doc.content },
]);
expect(updatedDocs).toBe(
[
"✏️ successfully updated 'simple-doc' with contents from __tests__/__fixtures__/existing-docs/simple-doc.md",
"✏️ successfully updated 'another-doc' with contents from __tests__/__fixtures__/existing-docs/subdir/another-doc.md",
].join('\n')
);

getMocks.done();
updateMocks.done();
versionMock.done();
});
});

it('should return doc update info for dry run', () => {
expect.assertions(1);

const getMocks = getNockWithVersionHeader(version)
.get('/api/v1/docs/simple-doc')
.basicAuth({ user: key })
.reply(200, { category, slug: simpleDoc.slug, lastUpdatedHash: 'anOldHash' })
.get('/api/v1/docs/another-doc')
.basicAuth({ user: key })
.reply(200, { category, slug: anotherDoc.slug, lastUpdatedHash: 'anOldHash' });

const versionMock = getApiNock()
.get(`/api/v1/version/${version}`)
.basicAuth({ user: key })
.reply(200, { version });

return docs
.run({ dryRun: true, folder: './__tests__/__fixtures__/existing-docs', key, version })
.then(updatedDocs => {
// All docs should have been updated because their hashes from the GET request were different from what they
// are currently.
expect(updatedDocs).toBe(
[
`🎭 dry run! This will update 'simple-doc' with contents from __tests__/__fixtures__/existing-docs/simple-doc.md with the following metadata: ${JSON.stringify(
simpleDoc.doc.data
)}`,
`🎭 dry run! This will update 'another-doc' with contents from __tests__/__fixtures__/existing-docs/subdir/another-doc.md with the following metadata: ${JSON.stringify(
anotherDoc.doc.data
)}`,
].join('\n')
);

getMocks.done();
versionMock.done();
});
});

it('should not send requests for docs that have not changed', () => {
expect.assertions(1);

Expand All @@ -144,15 +195,48 @@ describe('rdme docs', () => {
.reply(200, { version });

return docs.run({ folder: './__tests__/__fixtures__/existing-docs', key, version }).then(skippedDocs => {
expect(skippedDocs).toStrictEqual([
'`simple-doc` was not updated because there were no changes.',
'`another-doc` was not updated because there were no changes.',
]);
expect(skippedDocs).toBe(
[
'`simple-doc` was not updated because there were no changes.',
'`another-doc` was not updated because there were no changes.',
].join('\n')
);

getMocks.done();
versionMock.done();
});
});

it('should adjust "no changes" message if in dry run', () => {
expect.assertions(1);

const getMocks = getNockWithVersionHeader(version)
.get('/api/v1/docs/simple-doc')
.basicAuth({ user: key })
.reply(200, { category, slug: simpleDoc.slug, lastUpdatedHash: simpleDoc.hash })
.get('/api/v1/docs/another-doc')
.basicAuth({ user: key })
.reply(200, { category, slug: anotherDoc.slug, lastUpdatedHash: anotherDoc.hash });

const versionMock = getApiNock()
.get(`/api/v1/version/${version}`)
.basicAuth({ user: key })
.reply(200, { version });

return docs
.run({ dryRun: true, folder: './__tests__/__fixtures__/existing-docs', key, version })
.then(skippedDocs => {
expect(skippedDocs).toBe(
[
'🎭 dry run! `simple-doc` will not be updated because there were no changes.',
'🎭 dry run! `another-doc` will not be updated because there were no changes.',
].join('\n')
);

getMocks.done();
versionMock.done();
});
});
});

describe('new docs', () => {
Expand Down Expand Up @@ -181,21 +265,44 @@ describe('rdme docs', () => {
.basicAuth({ user: key })
.reply(200, { version });

await expect(docs.run({ folder: './__tests__/__fixtures__/new-docs', key, version })).resolves.toStrictEqual([
{
slug: 'new-doc',
body: '\nBody\n',
category: '5ae122e10fdf4e39bb34db6f',
title: 'This is the document title',
lastUpdatedHash: 'a23046c1e9d8ab47f8875ae7c5e429cb95be1c48',
},
]);
await expect(docs.run({ folder: './__tests__/__fixtures__/new-docs', key, version })).resolves.toBe(
"🌱 successfully created 'new-doc' with contents from __tests__/__fixtures__/new-docs/new-doc.md"
);

getMock.done();
postMock.done();
versionMock.done();
});

it('should return creation info for dry run', async () => {
const slug = 'new-doc';
const doc = frontMatter(fs.readFileSync(path.join(fixturesDir, `/new-docs/${slug}.md`)));

const getMock = getNockWithVersionHeader(version)
.get(`/api/v1/docs/${slug}`)
.basicAuth({ user: key })
.reply(404, {
error: 'DOC_NOTFOUND',
message: `The doc with the slug '${slug}' couldn't be found`,
suggestion: '...a suggestion to resolve the issue...',
help: 'If you need help, email support@readme.io and mention log "fake-metrics-uuid".',
});

const versionMock = getApiNock()
.get(`/api/v1/version/${version}`)
.basicAuth({ user: key })
.reply(200, { version });

await expect(docs.run({ dryRun: true, folder: './__tests__/__fixtures__/new-docs', key, version })).resolves.toBe(
`🎭 dry run! This will create 'new-doc' with contents from __tests__/__fixtures__/new-docs/new-doc.md with the following metadata: ${JSON.stringify(
doc.data
)}`
);

getMock.done();
versionMock.done();
});

it('should fail if any docs are invalid', async () => {
const folder = 'failure-docs';
const slug = 'fail-doc';
Expand Down Expand Up @@ -301,15 +408,9 @@ describe('rdme docs', () => {
.basicAuth({ user: key })
.reply(200, { version });

await expect(docs.run({ folder: './__tests__/__fixtures__/slug-docs', key, version })).resolves.toStrictEqual([
{
slug: 'marc-actually-wrote-a-test',
body: '\nBody\n',
category: 'CATEGORY_ID',
title: 'This is the document title',
lastUpdatedHash: 'c9cb7cc26e90775548e1d182ae7fcaa0eaba96bc',
},
]);
await expect(docs.run({ folder: './__tests__/__fixtures__/slug-docs', key, version })).resolves.toBe(
"🌱 successfully created 'marc-actually-wrote-a-test' with contents from __tests__/__fixtures__/slug-docs/new-doc-slug.md"
);

getMock.done();
postMock.done();
Expand Down
41 changes: 32 additions & 9 deletions src/cmds/docs/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,16 @@ module.exports = class DocsCommand {
type: String,
defaultOption: true,
},
{
name: 'dryRun',
type: Boolean,
description: 'Runs the command without creating/updating any docs in ReadMe. Useful for debugging.',
},
];
}

async run(opts) {
const { folder, key, version } = opts;
const { dryRun, folder, key, version } = opts;

debug(`command: ${this.command}`);
debug(`opts: ${JSON.stringify(opts)}`);
Expand Down Expand Up @@ -83,9 +88,15 @@ module.exports = class DocsCommand {
return Promise.reject(new Error(`We were unable to locate Markdown files in ${folder}.`));
}

function createDoc(slug, file, hash, err) {
function createDoc(slug, file, filename, hash, err) {
if (err.error !== 'DOC_NOTFOUND') return Promise.reject(err);

if (dryRun) {
return `🎭 dry run! This will create '${slug}' with contents from ${filename} with the following metadata: ${JSON.stringify(
file.data
)}`;
}

return fetch(`${config.get('host')}/api/v1/docs`, {
method: 'post',
headers: cleanHeaders(key, {
Expand All @@ -98,12 +109,22 @@ module.exports = class DocsCommand {
...file.data,
lastUpdatedHash: hash,
}),
}).then(res => handleRes(res));
})
.then(res => handleRes(res))
.then(res => `🌱 successfully created '${res.slug}' with contents from ${filename}`);
}

function updateDoc(slug, file, hash, existingDoc) {
function updateDoc(slug, file, filename, hash, existingDoc) {
if (hash === existingDoc.lastUpdatedHash) {
return `\`${slug}\` was not updated because there were no changes.`;
return `${dryRun ? '🎭 dry run! ' : ''}\`${slug}\` ${
dryRun ? 'will not be' : 'was not'
} updated because there were no changes.`;
}

if (dryRun) {
return `🎭 dry run! This will update '${slug}' with contents from ${filename} with the following metadata: ${JSON.stringify(
file.data
)}`;
}

return fetch(`${config.get('host')}/api/v1/docs/${slug}`, {
Expand All @@ -119,7 +140,9 @@ module.exports = class DocsCommand {
lastUpdatedHash: hash,
})
),
}).then(res => handleRes(res));
})
.then(res => handleRes(res))
.then(res => `✏️ successfully updated '${res.slug}' with contents from ${filename}`);
}

const updatedDocs = await Promise.all(
Expand Down Expand Up @@ -147,10 +170,10 @@ module.exports = class DocsCommand {
debug(`GET /docs/:slug API response for ${slug}: ${JSON.stringify(res)}`);
if (res.error) {
debug(`error retrieving data for ${slug}, creating doc`);
return createDoc(slug, matter, hash, res);
return createDoc(slug, matter, filename, hash, res);
}
debug(`data received for ${slug}, updating doc`);
return updateDoc(slug, matter, hash, res);
return updateDoc(slug, matter, filename, hash, res);
})
.catch(err => {
// eslint-disable-next-line no-param-reassign
Expand All @@ -160,6 +183,6 @@ module.exports = class DocsCommand {
})
);

return updatedDocs;
return chalk.green(updatedDocs.join('\n'));
}
};

0 comments on commit f86b5c6

Please sign in to comment.