Add writeFixture() and clearFixture() methods

[mrazauskas]

What if Poku would have writeFixture() and clearFixture() methods?

These are easy to implement on user side, but Poku implementation could:

• wrap around native fs of each platform (if that makes sense in this case?)
• always clean up any written fixtures at the end of test file (if that is possible?)

Bonus: perhaps Poku could use these methods in its own tests (;

I am not 100% sure if that is good idea. Just wanted to leave a note.

[mrazauskas]

Ah.. This reminded me the file System API from Japa: https://japa.dev/docs/plugins/file-system#file-system-api

[wellwelwel]

That's just an personal opinion, but for me it's relatively complex for a final user (I refer to the approach/usability itself):

test.group('Make files', (group) => {
  group.each.setup(({ context }) => {
    return () => context.fs.cleanup()
  })
})

[wellwelwel]

Hm... ☁️

Probably as an instanced class, like:

• Default usage:

// improvised name
useFixtures([
  {
    path: '.temp/foo.txt',
    content: '🐷',
  },
]);

test(() => { /* ... */ });

• Customized usage:

const fixtures = useFixtures([
  {
    path: '.temp/foo.txt',
    content: '🐷',
  },
]);

await fixtures.write(); // optional (should be called automatically as a `beforeEach`)
await fixtures.clear(); // optional (should be called automatically as a `afterEach`)

In that approach, it would be a kind of replacement for the beforeEach and afterEach hooks.

[wellwelwel]

This approach is very similar to current each hook set:

import { beforeEach, afterEach } from 'poku';

const before = beforeEach(() => true);
const after = afterEach(() => true);

before.pause();
before.continue();
before.reset();

after.pause();
after.continue();
after.reset();

• I just noticed that there are no examples of how to use these cases.

[wellwelwel]

What do you think, @mrazauskas? 🙋🏻‍♂️

[mrazauskas]

I looked through the codebase. In most of the cases fixtures are created for each test scope:

await describe("test scope", async () => {
  await test("first test", async () => {
    await writeFixture();

    // test logic

    await clearFixture();
  });

  await test("second test", async () => {
    await writeFixture();

    // test logic

    await clearFixture();
  });
});

Sometimes all tests in a describe() scope share a single fixture:

await describe("describe scope x", async () => {
  await writeFixture();

  for (const testCase of testCases) {
    await test(testCase, async () => {
      // test logic
    });
  }

  await clearFixture();
});

await describe("describe scope y", async () => {
  await writeFixture();

  await test("first test", async () => {
    // test logic
  });

  await test("second test", async () => {
    // test logic
  });

  await clearFixture();
});

At the moment there are no per file fixtures, i.e. beforeEach() style fixtures.

---

I think fixture should be created and disposed per scope, not globally. Somewhat similar to the using keyword.

So here is the proposed API:

await describe("test scope", async () => {
  await test("first test", async () => {
    await usingFixture(fixtureUrl, {
      ["dummyFile.js"]: dummyFileText,
      ["tsconfig.json"]: JSON.stringify(tsconfig, null, 2),
    });

    // test logic

    // the fixture is disposed by Poku
  });

  await test("second test", async () => {
    await usingFixture(fixtureUrl, {
      ["dummyFile.js"]: dummyFileText,
      ["tsconfig.json"]: JSON.stringify(tsconfig, null, 2),
    });

    // test logic

    // the fixture is disposed by Poku
  });
});

The describe() scope also works:

await describe("describe scope one", async () => {
  await usingFixture(fixtureUrl, {
    ["dummyFile.js"]: dummyFileText,
    ["tsconfig.json"]: JSON.stringify(tsconfig, null, 2),
  });

  for (const testCase of testCases) {
    await test(testCase, async () => {
      // test logic
    });
  }

  // the fixture is disposed by Poku
});

await describe("describe scope two", async () => {
  await usingFixture(fixtureUrl, {
    ["dummyFile.js"]: dummyFileText,
    ["tsconfig.json"]: JSON.stringify(tsconfig, null, 2),
  });

  await test("first test", async () => {
    // test logic
  });

  await test("second test", async () => {
    // test logic
  });

  // the fixture is disposed by Poku
});

And even global scope should work.

Notes:

• I call it fixture, because it is a single thing. It is created at once and removed all at once. Like a directory.
• hence the fixtureUrl: string | URL must point to a directory, that is created and later disposed.

[wellwelwel]

I accidentally deleted the documentation with examples of beforeEach and afterEach when bumping Poku to v2.

About the scope, it is in fact global, but when you define a new beforeEach, the previous beforeEach is overwritten (the same goes for afterEach).

• As they are expected to run one by one (both async and sync), I thought this would be a practical way to do it.

---

But if that causes any problem, we could have an approach with the context isolated.

[wellwelwel]

* I'm referring to beforeEach because it's the basis for the fixtures idea, where my intention would be to use a similar behavior.

[mrazauskas]

when you define a new beforeEach, the previous beforeEach will be replaced (the same goes for afterEach).

Sounds right. I was thinking: if next test() or describe() does not define a fixture, there should be none. In other words, when a fixture should be disposed? I think, if it was created for a particular test, there is no need to have it for the next test.

The same with beforeEach() / afterEach(). These might setup / clear state for a particular describe(), but the next describe() might not require any state handle. I have one or two cases like this. Now I am forced to create before and after variables and to call before.reset(), after.reset().

It feels like beforeEach() / afterEach() are leaking from one describe() to another. I understand this happens by design and documentation of describe() does not promise to isolate state. But.. If we talk about the JavaScript essence, what happens in a {} block stays in that {} block.

[wellwelwel]

If we talk about the JavaScript essence, what happens in a {} block stays in that {} block.

I agree, I think an approach to not causing a breaking change could be bring in an optional context parameter for describe, for example:

describe((ctx) => {
  ctx.beforeEach(() => true);
});

Then, in a major bump, we could remove the global beforeEach (or keep both, specifying in the documentation that out of context, hooks will be global).

[mrazauskas]

I like this idea! Context comes from context and the rest global. That sounds very very good.